home *** CD-ROM | disk | FTP | other *** search
/ Collection of Internet / Collection of Internet.iso / infosrvr / doc / www_serv.txt < prev    next >
Text File  |  1993-09-29  |  116KB  |  2,727 lines
  1.                           W3 SERVER SOFTWARE
  2.                                    
  3.  A W3 server, like the ftp daemon , is a program which responds to an
  4.  incoming tcp connection and provides a service to the caller.  There
  5.  are many varieties of W3 server software to serve different forms of
  6.  data.
  7.  
  8. Basic W3 servers
  9.  
  10.   CERN server             The basic W3  daemon program serves files
  11.                          already in hypertext or plain text.  This
  12.                          daemon then is used as a basis for many other
  13.                          types of server and gateways .
  14.                          
  15.   NCSA server             A server for files, written in C, public
  16.                          domain.  Runs on top of a gopher-style
  17.                          database just like "gopherd".
  18.                          
  19.   Perl server             from Marc VanHeyningen at Indiana
  20.                          University. Wriiten in perl .
  21.                          
  22.   Plexus                  Tony Sander's engversion of Marc VH's.
  23.                          
  24.   MacHTTPD                Server for the Macintosh
  25.                          
  26.   REXX for VM             A server consisting of a amall C program
  27.                          which passes control to a  server written in
  28.                          REXX.
  29.                          
  30.  Whatever server you are running, you will probably be interested in:
  31.  
  32.       Tools for information providers
  33.       
  34.       Syle Guide for Online Hypertext
  35.       
  36. Making a new server
  37.  
  38.  This daemon is often used as a basis for a more specific server for a
  39.  given application.  A server which allows a world of data to be seen
  40.  as part of the W3 universe is known as a gateway.  (Most servers
  41.  could therefore be regarded as gateways, but the term implies some
  42.  conversion or mapping between dissimilar worlds) .  For  short
  43.  tutorials with examples, see:
  44.  
  45.       Writing a server in C
  46.       
  47.       Writing a server as a script
  48.       
  49.  It is a good idea to pick the basic daemon or one of the servers in
  50.  the list as a starting point when making a new server.
  51.  
  52. Other servers and Gateways
  53.  
  54.  
  55.  
  56.  
  57. T. Berners-Lee                                                       1
  58.  
  59.                                  WWW Server Guide)        14 July 1993
  60.  
  61.  These are servers which provide data extracted from other systems.
  62.  they are built using code from the basic daemon, or scripts. See
  63.  
  64.       List of Gateways available .
  65.       
  66.                                                                 Tim BL
  67.                                                                       
  68. About documents generated from hypertext
  69.  
  70.  Paper manuals generated from hypertext are made for convenience, for
  71.  example for reading when one has no computer to turn to.  We have
  72.  tried to make the hypertext into fairly conventional paper documents,
  73.  but they may seem a little strange in some ways.
  74.  All the links have been removed. Therefore, it is worth looking at
  75.  the table of contents to see what there is in the manual.  Something
  76.  which is not explained in place may be explained in detail elsewhere.
  77.  We have tried to keep related matter together, but sometimes
  78.  necessarily you might have to check the table of contents to find it.
  79.  Please remember that these are for the most part "living documents".
  80.  That is, they are constantly changing to reflect current knowledge.
  81.  If you see a statement such as "Product xxx does not support this
  82.  feature", remember that it was the case when the document was
  83.  generated, and may not be the same now.   So if in doubt, check the
  84.  online version. Of course, the living document may be out of date
  85.  too, in which case it is helpful to mail its author.
  86.  
  87.                                                                 Tim BL
  88.                                                                       
  89.                         WWW SERVER USER GUIDE
  90.                                    
  91.  The basic WWW server allows files and directories in a file system to
  92.  be server to the world as menu trees, multimedia, and/or hypertext.
  93.  The http daemon, httpd , is a general server program which runs a w3
  94.  protocol, " HTTP ".   This is a TCP/IP based protocol running by
  95.  convention on port 80.
  96.  
  97. In this guide
  98.  
  99.   Distribution            How to get the code.
  100.                          
  101.   Compilation             The daemon is compiled in the same way as
  102.                          the library and line mode browser -- see WWW
  103.                          distributed code .
  104.                          
  105.   Installation            How to install a server under unix internet
  106.                          daemon
  107.                          
  108.   Options                 Command line options at run time
  109.                          
  110.   Rule File               The format of a rule file. By default,
  111.                          /etc/httpd.conf
  112.                          
  113.   Etiquette               Conventions you should follow to make life
  114.  
  115. T. Berners-Lee                                                       2
  116.  
  117.                                  WWW Server Guide)        14 July 1993
  118.  
  119.                          smoother
  120.                          
  121.   Debugging               If it doesn't seem to work
  122.                          
  123.   Known bugs              and improvements desired
  124.                          
  125.   Change History          change list of improvements made and bug
  126.                          fixes.
  127.                          
  128. Related documents
  129.  
  130.   HTML specification      A description of the hypertext markup
  131.                          language used for representing menus, etc
  132.                          
  133.   HTTP specification      A desription of the protocol used by the
  134.                          server.
  135.                          
  136. Status of basic WWW server
  137.  
  138.  A basic fast information server for files.
  139.  
  140.   Author                  TBL
  141.                          
  142.   Status:                 Version  2 available by anonymous FTP, with
  143.                          no index search but file access, name mapping
  144.                          and security filter, ability to act as
  145.                          gateway for anything in the WWW library's
  146.                          repertoire, including WAIS.
  147.                          
  148.   Plans:                  A version which will allow general unix
  149.                          users to set up an index search daemon. As
  150.                          index search tools are not generally
  151.                          available, we may use the NeXT digital
  152.                          Librarian or WAIS as an basis.
  153.                          
  154.   Platforms               Unix, VMS, VM/CMS (VM/XA).
  155.                          
  156.   Next Milestone:         Run shell scripts to implement virtual
  157.                          documents and searches.
  158.                          
  159.   More information:       User guide ,  Bug list , Internals ,  Change
  160.                          history .
  161.                          
  162.   Wider scope:            W3 servers , Other WWW software
  163.                          
  164.  Features include
  165.  
  166.       Installation under inetd or run stand-alone
  167.       
  168.       Can be run stand-alone by normal user
  169.       
  170.       Automatically generates hypertext view of directory tree
  171.  
  172.  
  173. T. Berners-Lee                                                       3
  174.  
  175.                                  WWW Server Guide)        14 July 1993
  176.  
  177.       
  178.       Uses "README" files to document directory listings
  179.       
  180.       Handles multimple formats of same file, selects format
  181.       apropriate for client  capabilities
  182.       
  183.       Document name to filename mapping for longer-lived document
  184.       names
  185.       
  186.       Can act as gateway for WAIS, news, etc if needed
  187.       
  188. WorldWideWeb distributed code
  189.  
  190.  See the CERN copyright .  This is the README file which you get when
  191.  you unwrap one of our tar files. These files contain information
  192.  about hypertext, hypertext systems, and the WorldWideWeb project. If
  193.  you have taken this with a .tar file, you will have only a subset of
  194.  the files.
  195.  THIS FILE IS A VERY ABRIDGED VERSION OF THE INFORMATION AVAILABLE ON
  196.  THE WEB.   IF IN DOUBT, READ THE WEB DIRECTLY. If you have not got
  197.  ANY browser installed yet, do this by telnet to info.cern.ch (no
  198.  username or password).
  199.  
  200.   ARCHIVE DIRECTORY STRUCTURE
  201.  Under /pub/www, besides this README file, you'll find bin, src and
  202.  doc directories.  The main archives are as follows:
  203.  
  204.   bin/xxx/bbbb            Executable binaries of program bbbb for
  205.                          system xxx. Check what's there before you
  206.                          bother compiling. (Note HP700/8800 series is
  207.                          "snake")
  208.                          
  209.   bin/next/WorldWideWeb_v.vv.tar.Z
  210.                          The Hypertext Browser/editor for the NeXT --
  211.                          binary.
  212.                          
  213.   src/WWWLibrary_v.vv.tar.Z
  214.                           The W3 Library. All source, and Makefiles
  215.                          for selected systems.
  216.                          
  217.   src/WWWLineMode_v.vv.tar.Z
  218.                           The Line mode browser - all source, and
  219.                          Makefiles for selected systems. Requires the
  220.                          Library .
  221.                          
  222.   src/WWWDaemon_v.vv.tar.Z
  223.                           The HTTP daemon, and WWW-WAIS  gateway
  224.                          programs. Source.  Requires the Library.
  225.                          
  226.   src/WWWMailRobot_v.vv.tar.Z
  227.                           The Mail Robot.
  228.                          
  229.  
  230.  
  231. T. Berners-Lee                                                       4
  232.  
  233.                                  WWW Server Guide)        14 July 1993
  234.  
  235.   doc/WWWBook.tar.Z       A snapshot of our internal documentation -
  236.                          we prefer you to access this on line -- see
  237.                          warnings below.
  238.                          
  239.   BASIC WWW SOFTWARE INSTALLATION FROM SOURCE
  240.  This applies to the line mode client and the server.  Below, $prod
  241.  means LineMode or Daemon depending on which you are building.
  242.  
  243.     Generated Directory structure
  244.  The tar files are all designed to be unwrapped in the same (this)
  245.  directory. They create different parts of a common directory tree
  246.  under that directory. There may be some duplication. They also
  247.  generate a few files in this directory: README.*, Copyright.*, and
  248.  some installation instructions (.txt).
  249.  The directory structure is, for product $prod  and machine $WWW_MACH
  250.  
  251.   WWW/$prod/Implementation
  252.                           Source files for a given product
  253.                          
  254.   WWW/$prod/Implementation/CommonMakefile
  255.                          The machine-independent parts of the Makefile
  256.                          for this product
  257.                          
  258.   WWW/$prod/$WWW_MACH/    Area for compiling for a given system
  259.                          
  260.   WWW/All/$WWW_MACH/Makefile.include
  261.                          The machine-dependent parts of the makefile
  262.                          for any product
  263.                          
  264.   WWW/All/Implementation/Makefile.product
  265.                          A makefile which includes both parts above
  266.                          and so can be used from any product, any
  267.                          machine.
  268.                          
  269.     Compilation on already supported platforms
  270.  You must get the WWWLibrary tar file as well as the products you want
  271.  and unwrap them all from the same directory.
  272.  You must define the environmant variable WWW_MACH to be the
  273.  architecure of your machine (sun4, decstation, rs6000, sgi, snake,
  274.  etc)
  275.  In directory WWW, type BUILD.
  276.  
  277.     Compilation on new platforms
  278.  If your machine is not on the list:
  279.  
  280.       Make up a new subdirectory of that name under WWW/$prod and
  281.       WWW/All, copying the contents of a basically similar
  282.       architecture's directory.
  283.       
  284.       Check the  WWW/All/$WWW_MACH/Makefile.include for suitable
  285.       directory and flag definitions.
  286.       
  287.       Check the file tcp.h for the system-specific include file
  288.  
  289. T. Berners-Lee                                                       5
  290.  
  291.                                  WWW Server Guide)        14 July 1993
  292.  
  293.       coordinates, etc.
  294.       
  295.       Send any changes you have to make back to
  296.       www-request@info.cern.ch for inclusion into future releases.
  297.       
  298.       Once you have this set up, type BUILD.
  299.       
  300.   NEXTSTEP BROWSER/EDITOR
  301.  The browser for the NeXT is those files contained in the application
  302.  directory WWW/Next/Implementation/WorldWideWeb.app and is compiled.
  303.  When you install the app, you may want to configure the default page,
  304.  WorldWideWeb.app/default.html. These must point to some useful
  305.  information! You should keep it up to date with pointers to info on
  306.  your site and elsewhere. If you use the CERN home page note there is
  307.  a link at the bottom to the master copy on our server.   You should
  308.  set up the address of your local news server with
  309.  
  310.                       dwrite WorldWideWeb NewsHost  news
  311.  
  312.  replacing the last word with the actual address of your news host.
  313.  See Installation instructions .
  314.  
  315.   LINE MODE BROWSER
  316.  Binaries of this for some systems are available in /pub/www/bin/ .
  317.  The binaries can be picked up, set executable, and run immediately.
  318.  If there is no binary, see "Installation from source" above.
  319.   (See Installation notes ).  Do the same thing (in the same
  320.  directory) to the WWWLibrary_v.cc.tar.Z file to get the common
  321.  library.
  322.  You will have an ASCII printable manual in the file
  323.  WWW/LineMode/Defaults/line-mode-guide.txt which you can print out at
  324.  this stage. This is a frozen copy of some of the online
  325.  documentation.
  326.  Whe you install the browser, you may configure a default page. This
  327.  is /usr/local/lib/WWW/default.html for the line mode browser. This
  328.  must point to some useful information! You should keep it up to date
  329.  with pointers to info on your site and elsewhere. If you use the CERN
  330.  home page note there is a link at the bottom to the master copy on
  331.  our server.
  332.  Some basic documentation on the browser is delivered with the home
  333.  page in the directory WWW/LineMode/Defaults. A separate tar file of
  334.  that directory (WWWLineModeDefaults.tar.Z) is available if you just
  335.  want to update that.
  336.  The rest of the documentation is in hypertext, and so wil be readable
  337.  most easily with a browser. We suggest that after installing the
  338.  browser, you browse through the basic documentation so that you are
  339.  aware of the options and customisation possibilities for example.
  340.  
  341.   SERVER
  342.  The server can be run very simply under the internet  daemon, to
  343.  export a file directory tree as a browsable hypertext tree.  Binaries
  344.  are avilable for some platofrms, otherwise follow instructions above
  345.  
  346.  
  347. T. Berners-Lee                                                       6
  348.  
  349.                                  WWW Server Guide)        14 July 1993
  350.  
  351.  for compiling and then go on to " Installing the basic W3 server ".
  352.  
  353.   XMOSAIC
  354.  XMosaic is an X11/Motif  W3 browser.
  355.  The sources and binaries are distributed separately from
  356.  FTP.NCSA.UIUC.EDU, in  /Web/xmosaic.  Binaries are available for some
  357.  platforms.  If you have to build from source, check the README in the
  358.  distribution.
  359.  The binaries can be picked up, uncompressed, set "executable" and run
  360.  immediately.
  361.  
  362.   VIOLA BROWSER FOR X11
  363.  Viola is an X11 application for reading global hypertext.  If a
  364.  binary is available from your machine, in /pub/www/bin/.../viola*,
  365.  then take that and also the Viola "apps" tar file which contains the
  366.  scripts you will need.
  367.  To generate this from source, you will need both the W3 library and
  368.  the Viola source files.  There is an Imakefile with the viola source
  369.  directory. You will need to generate the XPA and XPM libraries and
  370.  the W3 library befere you make viola itself.
  371.  
  372.   DOCUMENTATION
  373.  In the /pub/www/doc directory are a number articles, preprints and
  374.  guides on the web.
  375.  See the online WWW bibliography for a list of these and other
  376.  articles, books, etc. and also the list of WWW Manuals available in
  377.  text and postscript form.
  378.  
  379.   GENERAL
  380.  Your comments will of course be most appreciated, on code, or
  381.  information on the web which is out of date or misleading. If you
  382.  write your own hypertext and make it available by anonymous ftp or
  383.  using a server, tell us and we'll put some pointers to it in ours.
  384.  Thus spreads the web...
  385.  
  386.                                                        Tim Berners-Lee
  387.                                                                       
  388.                                                   WorldWideWeb project
  389.                                                                       
  390.                                      CERN, 1211 Geneva 23, Switzerland
  391.                                                                       
  392.  Tel: +41 22 767 3755; Fax: +41 22 767 7155; email: timbl@info.cern.ch
  393.                                                                       
  394. Installing the basic WWW server
  395.  
  396.  Instructions for installing it under unix using the inet daemon are
  397.  here.
  398.  There are special instructions if you are installing under VMS .
  399.  The usual way to install a daemon is to either run it from the
  400.  bootstrap command file (for example /etc/rc) so that it runs
  401.  continuously, or to set up the internet daemon (inetd) to run it when
  402.  a call comes in.
  403.  
  404.  
  405. T. Berners-Lee                                                       7
  406.  
  407.                                  WWW Server Guide)        14 July 1993
  408.  
  409.  See a csh script which does everything below for unix BSD systems but
  410.  which you should modify with care for your own system.
  411.  Note: With  version 2.0 on, a rule file is no longer essential if you
  412.  want to just export a directory tree.
  413.  The installation normally requires superuser status, but it is
  414.  poosible to run httpd from a terminal session as a normal user.
  415.  
  416.   LOG FILE
  417.  If  a log file is required,  make sure that the user name under which
  418.  the daemon is run  has the right to write the file
  419.  
  420.                                                                 Tim BL
  421.                                                                       
  422.   PRIVILIGED PORTS
  423.   
  424.    The TCP/IP port numbers below 1024 are special in that normal users
  425.    are not  allowed to run servers on them.  This is a security
  426.    feaure, in that if you connect to a service on one of these ports
  427.    you are fairly sure that you have the real thing, and not a fake
  428.    which some hacker has put up for you.
  429.    
  430.    The normal port number for W3 servers is port 80, which is such a
  431.    port. (This number is assigned by the Internet Assigned Numbers
  432.    Authority, IANA).
  433.    
  434.    When you run a server as a test from a non-priviliged account, you
  435.    will normally test it on other ports, such as 2784 or 5000
  436.    typically.
  437.    
  438.     Under unix
  439.     
  440.    The inet daemon (running as root) can listen for incomming
  441.    conections on port 80 and pass them down to a process with a safer
  442.    uid for the server itself. Of course, you have to be root to set up
  443.    the inet daemon.
  444.    
  445.     Under VMS
  446.     
  447.    Under UCX, The process running as a server needs BYPASS privilege
  448.    to listen to ports below 1024.  This might mean you have to install
  449.    the server.  With other TCP/IP packages, privilege of some sort is
  450.    similarly required.
  451.    
  452.    _________________________________________________________________
  453.    
  454.                                                                 Tim BL
  455.                                                                       
  456.   INSTALLING A DAEMON UNDER INETD
  457.  This is how to to set up the internet daemon (inetd) to run your
  458.  HTTPD server whenever a request comes in.   (These steps are the same
  459.  for any daemon under unix: you will probably find a similar thing has
  460.  been done for the FTP daemon, ftpd, for example.)
  461.  
  462.  
  463. T. Berners-Lee                                                       8
  464.  
  465.                                  WWW Server Guide)        14 July 1993
  466.  
  467.  
  468.     Step1
  469.  Copy the daemon program or shell script ( httpd in this example) into
  470.  a suitable directory such as /usr/etc. Protect it from anyone writing
  471.  to it except root.
  472.  
  473.     Step2
  474.  Put "http" in the /etc/services file, or use the name of a specific
  475.  service of your own if you want to use have a special port number.
  476.   (Exceptions: on a NeXT, see  using the NetInfomanager . On any
  477.  machine running NIS (yellow pages), see specicial instructions ).
  478.  For example,
  479.  
  480. http            80/tcp                  # WorldWideWeb server
  481.  
  482.     Step3
  483.  Put a line in the internet daemon configuration file,
  484.  /etc/inetd.conf. For example,
  485.  
  486. http    stream  tcp     nowait  nobody  /usr/etc/httpd          httpd
  487. /Public
  488.  
  489.  (That was all one line.) Here "http" is used as a link between the
  490.  services file and inetd.conf: it could have been any identifier.
  491.  "nobody" is the user name under which you want the daemon to run,
  492.  which determines what privileges it has for example to read data.
  493.  "/usr/etc/httpd" is the actual file name of the server. The rest of
  494.  the line is the arguments passed to httpd: arg0 is the program name,
  495.  "httpd",  by convention. Here the argument "/Public"  is the
  496.  directory tree to be exported. This is in fact the default if no
  497.  directory is given. See command line syntax for more details.
  498.  Note: The inted.conf format varies from system to system. If in
  499.  doubt, copy the format of other lines in your existing inted.conf.
  500.  For example, under ultrix there is no user name field -- everything
  501.  runs as root.
  502.  Note: there seem to be, on the NeXT at least, a limit of 4 arguments
  503.  passed across by inetd!
  504.  
  505.     Step 4
  506.  When you have updated inted.conf, find out which process is running
  507.  inetd, and send it a "HUP" signal.  On BSD unix (For system V, use
  508.  ps-el for ps aux) this looks like:
  509.  
  510.                 
  511.                 > ps aux | grep inetd | grep -v grep
  512.                 root        85   0.0  0.9 1.24M  304K ?  S     0:01 /u
  513. sr/etc/inetd
  514.                 > kill -HUP 85
  515.                 >
  516.  
  517.  
  518.     Test it
  519.  
  520.  
  521. T. Berners-Lee                                                       9
  522.  
  523.                                  WWW Server Guide)        14 July 1993
  524.  
  525.  Test the server with the line mode browser by giving its address
  526.  explicitly:
  527.  
  528.                         www http://myhost.dom.ain/welcome.html
  529.  
  530.  This assumes that you have a file "welcome.html" in your exported
  531.  directory.  If it doesn't work, you have probably missed something.
  532.  See notes on debugging .
  533.  
  534.                                                                 Tim BL
  535.                                                                       
  536.   USING NIS (YELLOW PAGES)
  537.  If your machine is running Sun's "Network Information Service",
  538.  originally know as 'yellow pages", read this.
  539.  You must:
  540.  
  541.       First make an addition to the /etc/services file just as for a
  542.       normal unix system.
  543.       
  544.       Then, change directory to /var/yp and type "make".
  545.       
  546.  This will  load the /etc/services file info the yellow pages
  547.  information system.
  548.  Some peopl ehave found that they needed to reboot he system afterward
  549.  for the change to take effect.
  550.  
  551.                                                                 Tim BL
  552.                                                                       
  553.   ADDING A SERVICE ON THE NEXT
  554.  The NeXT uses the the "netinfo" database instead of the /etc/services
  555.  file.  This is managed with the /NextAdmin/NetInforManager
  556.  application. Here's how to add the service "www":
  557.  
  558.       Start the NetInfomanager by  double-clicking on its icon.
  559.       
  560.       If you are operating in a cluster,  open either your local
  561.       domain (/hostname) or if you have authority, the whole cluster
  562.       domain (/). If you're not in a cluster,  just use the domain you
  563.       are presented with.
  564.       
  565.       Select "services" from the browser tree.
  566.       
  567.       Select "ftp" from the list of services
  568.       
  569.       Select "dupliacte" from the edit menu.
  570.       
  571.       Select "copy of  ftp" and double-click on its icon to get
  572.       theproperty editor.
  573.       
  574.       Click on  "name" and then on the value "copy of ftp". Change
  575.       this to "www" by typing "www" in the window at the botton, and
  576.       hitting return.
  577.  
  578.  
  579. T. Berners-Lee                                                       10
  580.  
  581.                                  WWW Server Guide)        14 July 1993
  582.  
  583.       
  584.       Click on "port", and then on the value "21". Change it to "80".
  585.       
  586.       Use "Directory:Save" menu (Command/s) to save the result. You
  587.       will have to give a root password or netinfo manager password.
  588.       
  589.                                                                 Tim BL
  590.                                                                       
  591. The Rule File
  592.  
  593.  The rule file (configuration file) defines how the WWW software will
  594.  translate a request into a document name.   For a server, it allows
  595.  one to provide an extra level of  name mapping above that given by
  596.  links in the file system. It allows, for example, out of date names
  597.  to mapped onto their more recent counterparts.
  598.  For the client, it allows access to certain servers to be remapped
  599.  for example caching servers, or to local copies of the same
  600.  information.
  601.  The rule file also allows access to be restricted.  This is
  602.  essential, to prevent, for example, unauthorized access to your
  603.  password file.
  604.  By default, the rule file /etc/httpd.conf is loaded, unless specified
  605.  otherwise with the -R or -r options .
  606.  See also: example rule files , Old format for software before 2.0,
  607.  Setting up gateways, Firewall gateways.
  608.  
  609.   FORMAT
  610.  Each line consists of an operation code and one or two parameters,
  611.  referred to as the template and the result. Anything on a line after
  612.  and including a hash sign (#) is ignored, as are empty lines.
  613.  The server uses the top rule first, then EACH SUCCESSIVE RULE  unless
  614.  told otherwise by PASS or FAIL. The operation codes are as follows
  615.  
  616.   map template result     If the address matches the template, use the
  617.                          result string from now on for future rules.
  618.                          
  619.   pass template           If the address maches the template, use it
  620.                          as it is, porocessing no further rules.
  621.                          
  622.   pass template result    If the string matches the template, use the
  623.                          result string as it is, processing no futher
  624.                          rules.
  625.                          
  626.   fail template           If the address matches the template,
  627.                          prohibit access, processing no futher rules.
  628.                          
  629.  The template string may contain at most one wildcard asterisk ("*").
  630.  The result string may have one wildcard only if the template has one.
  631.  When matching,
  632.  
  633.       Rules are scanned from the top of the file to the bottom.
  634.       
  635.  
  636.  
  637. T. Berners-Lee                                                       11
  638.  
  639.                                  WWW Server Guide)        14 July 1993
  640.  
  641.       If a request matches a "map" template exactly, the result string
  642.       is used instead of the original string and applied to successive
  643.       rules.
  644.       
  645.       If the request maches a "map" template with wildcard, then the
  646.       text of the request which matches the wildcard is inserted in
  647.       place of the wildcard in the result string to form the
  648.       translated request. If the result string has no wildcard, it is
  649.       used as it is.
  650.       
  651.       When a map substitution takes place, the rule scan continues
  652.       with the next rule using the new string in place of the request.
  653.        This is not the case if a pass ro fail is matched: they
  654.       terminate the rule scan.
  655.       
  656.   SUFFIX DEFINITIONS
  657.  As well as any mapping lines in the rule file, the rule file may be
  658.  used to define the data types of files with particular suffixes.  The
  659.  syntax
  660.  
  661.                 suffix  <suffix>  <representation> <encoding> [ <quali
  662. ty> ]
  663.  
  664.  for example:
  665.  
  666.                 suffix  .pc     text/plain          7bit        1.0
  667.                 suffix  *.*     application/binary  binary      0.1
  668.                 suffix  *       text/plain          7bit
  669.  
  670.  
  671.  The parameters are as follows:
  672.  
  673.   <suffix>                The last part of the filename. There are two
  674.                          special cases. "*.*" matches to all files
  675.                          which have not been matched by any explicit
  676.                          suffixes but do contain a dot. "*" by itself
  677.                          matches to any file which does not match any
  678.                          other suffix.
  679.                          
  680.   <representation>        A MIME "content-type" style description of
  681.                          the repreentation in fact in use in the file.
  682.                           See the HTTP spec.  This need not be a real
  683.                          MIME type -- it will only be used if it
  684.                          matches a type given by a client.
  685.                          
  686.   <encoding>              A MIME content transfer encoding type.  Much
  687.                          more limited in variety than representations,
  688.                          basically whether the file is ASCII (7bit or
  689.                          8bit) or binary. A few other encodings are
  690.                          allowed, and maybe extension to compression.
  691.                          
  692.   <quality>               Optional. A floating point number between
  693.                          0.0 and 1.0 which determines the relative
  694.  
  695. T. Berners-Lee                                                       12
  696.  
  697.                                  WWW Server Guide)        14 July 1993
  698.  
  699.                          merits of files xxx.* which differ in their
  700.                          suffix only, when a link to xxx.multi is
  701.                          being resolved.  Defaults to 1.0.
  702.                          
  703.   PRESENTATION DEFINITIONS
  704.  In the rule file for a client, you can define the presentation of a
  705.  given data type. The syntax is
  706.  
  707.                 presentation   <representation>  <command-string>
  708.  
  709.  where the parameters are
  710.  
  711.   <representation>        A MIME-style content type. You can use
  712.                          regulare MIME types, such as image/jpeg, or
  713.                          your own extensions which start with x-, such
  714.                          as image/x-tiff, application/x-my-app.  See
  715.                          also above .
  716.                          
  717.   <command string>        The command needed to display a temporary
  718.                          file of this type.  A "%s" within this string
  719.                          will be replaces with the name of the
  720.                          temporary file.  Note that is any file suffix
  721.                          has been specified as corresenponding to this
  722.                          representation, then the temporarty file will
  723.                          be give that (or the first if there is a
  724.                          choice) suitable suffix.
  725.                          
  726.                                                                 Tim BL
  727.                                                                       
  728.   RULE FILE EXAMPLES
  729.  A basic rule file for the http daemon might look like this (it looked
  730.  different before version 2.0 ):
  731.  
  732.  
  733. pass    /          file:/u/john/welcome.html
  734. pass    /*         file:/u/john/public/*
  735. fail   *
  736.  
  737.  The first line maps the root document onto a specific document about
  738.  the server, and accepts it.  (see etiquette about the welcome page)
  739.  The second line maps all document names onto filenames in a
  740.  particular directory and accepts them.
  741.  The third line disallows access to all other documents. (There won't
  742.  be in any in this case because of the mapping, but its wise to put in
  743.  for later).
  744.  
  745.     Second example
  746.     
  747.  
  748. map    /            /tnotes/welcome.html
  749. map    /tnotes/*    file:/u/john/public/*
  750. map    /seminars/*  file:/u/jane/seminars/*
  751.  
  752.  
  753. T. Berners-Lee                                                       13
  754.  
  755.                                  WWW Server Guide)        14 July 1993
  756.  
  757. pass   file:/u/john/public/*
  758. pass   file:/u/jane/seminars/*.html
  759. fail   *
  760.  
  761.  The first line maps the root document onto a specific document about
  762.  the server.   Because it is "map and not "pass",  it DOESN'T accept
  763.  it  but passes it on for futher mapping by lines futher down.
  764.  The second line maps all document names starting with /tnote/ onto
  765.  filenames in a particular directory where john maintains the
  766.  technical notes. If someone else takes over the technical notes, we
  767.  can change this. Here we are starting to distinguish between document
  768.  names and file names. This can be carried much further if necessary,
  769.  but one level of mapping is enough to allow for changes of
  770.  administration of different areas.
  771.  The third line separately maps the seminar information into Jane's
  772.  directory.
  773.  The fourth and fifth line enable access to anything in John's
  774.  "public" directory, and any .html file in Jane's "seminar" directory
  775.  tree. Note here that the * maps to any sequence INCLUDING SLASHES so
  776.  all files in any subdirectory of /u/jane/seminars will be enabled so
  777.  long as they end in .html.
  778.  The bottom line will pick up for example any attempt to use the
  779.  server to access non-html files in Jane's seminars directory.
  780.  
  781.     Configuration file for a WAIS gateway
  782.  The httpd daemon can be used as a WAIS gateay if it has been compiled
  783.  with the necessary options and linked with the freeWAIS software. A
  784.  suitable configuration file is
  785.  
  786. map     /*              wais://*
  787. pass    wais://*
  788. fail    *
  789.  
  790.  
  791. Server Command Line
  792.  
  793.  The command line syntax for the basic www server allows a number of
  794.  options and an optional directory argument.
  795.  
  796.                         httpd  [options] [directory]
  797.  
  798.  The directory argument, if present, indicates the directory to be
  799.  exported. (Version 2.0 and later only.)  If not present, either a
  800.  rule file is be used, to export combinations of directories, or else
  801.  the default is to export the "/Public" directory tree.
  802.  
  803.   EXAMPLES
  804.   
  805.                         httpd -p 80  -dyt /ftp/pub
  806.  
  807.  This exports the entire /ftp/pub tree with browsable directories and
  808.  README files included at the top of directory listings.
  809.  
  810.  
  811. T. Berners-Lee                                                       14
  812.  
  813.                                  WWW Server Guide)        14 July 1993
  814.  
  815.  
  816.                         httpd
  817.  
  818.  This comamnd in the inetd configuration file inetd.conf exports the
  819.  /Public directory tree.  This tree may contain soft links to other
  820.  directory trees.
  821.  
  822.   -dn                     Disable directory browsing. An attempt to
  823.                          access a directory will generate an error
  824.                          response.
  825.                          
  826.   -dy                     Enable direcory browsing.  Directories are
  827.                          returned as hypertext documents. See browsing
  828.                          directories . This is the default.
  829.                          
  830.   -ds                     Enable directory browsing only for
  831.                          directories containing a file named
  832.                          ".www_browsable".
  833.                          
  834.   -dt                     For any browsable directory which contains a
  835.                          README file, include the text of the README
  836.                          file at the top of the document before the
  837.                          listing. This is the default.
  838.                          
  839.   -db                     As -dt but put the README at the bottom,
  840.                          after the listing.  The -db and -dt options
  841.                          may be combined with -dy as -dyb, -dty etc.
  842.                          
  843.   -dr                     Disables the README inclusion feature .
  844.                          
  845.   -l  file                Log all calls to the given file. The file is
  846.                          appended to if it already exists.
  847.                          
  848.   -p port                 Specify the port number. If this option is
  849.                          not given, the daemon assumes that it has
  850.                          been run by inetd, and uses stdin and stdout
  851.                          as its communication channel . Note that port
  852.                          numbers under 1024 are privileged .
  853.                          
  854.   -v                      Verbose mode. Copious trace messages are
  855.                          written to the standard output stream. Mainly
  856.                          for debugging.
  857.                          
  858.   -r file                 Load a rule file . The rules are added after
  859.                          any rules already loaded.  Inhibits the
  860.                          loading of the default rule file.
  861.                          
  862.   -R                      Do not use. Inhibit the loading of the
  863.                          default rule file.  Warning: running without
  864.                          a rule file  normally poses a security
  865.                          problem.  It won't work in general as only
  866.                          the path part of a URL is input into the rule
  867.  
  868.  
  869. T. Berners-Lee                                                       15
  870.  
  871.                                  WWW Server Guide)        14 July 1993
  872.  
  873.                          file, and a fully qualifiue URL (with file:
  874.                          in front for example) is required on output.
  875.                          
  876.                                                                 Tim BL
  877.                                                                       
  878. Debugging the daemon
  879.  
  880.  Suppose you think you have installed a W3 server but it doesn't work.
  881.  That is, you have followed the installation instructions and the test
  882.  at the end fails. Here we assume you have used port 80.  If you have
  883.  a situation not handled by this problem-solving guide, please mail
  884.  me.
  885.  Type
  886.  
  887.         www http://myhost.domain:80/
  888.  
  889.  
  890.  What happens?
  891.  
  892.       "Cannot connect to information server" message, "Unable to
  893.       access document" or some other generic-sounding error message
  894.       
  895.       An empty document is displayed
  896.       
  897.       A document containing the words "Document address invalid or
  898.       access not authorised", or some "Error 500" message is displayed
  899.       
  900.       A document is displayed, but not what you wanted the server to
  901.       give in response to that document name (/)
  902.       
  903.                                                                 Tim BL
  904.                                                                       
  905.   DOCUMENT ADDRESS INVALID
  906.  You have accessed a W3 server and you get back a message "Document
  907.  address invalid or access not authorized", or some other error
  908.  message from the server.
  909.  The 1.x server does not (originally for security reasons)
  910.  distringuish between a document which does not exist, and one to
  911.  which you are not allowed access.  However, most server are public
  912.  servers which allow access to anyone, so if you are following a bona
  913.  fide link, this could mean
  914.  
  915.       You have been passed a bad document address. If you are
  916.       following a link, check with the author of the document which
  917.       contained the link.
  918.       
  919.       The document has been moved. Check with the server
  920.       administrator. You should be able to find out who runs the
  921.       server by going to the welcome page (type "g /" with the line
  922.       mode browser) and seeing a link to information about the
  923.       maintainers.
  924.       
  925.  
  926.  
  927. T. Berners-Lee                                                       16
  928.  
  929.                                  WWW Server Guide)        14 July 1993
  930.  
  931.  If you are the server administrator, and you can't  understand why
  932.  the daemon refuses to deliver the file,
  933.  
  934.       Check the rule file if you have one.  Think out way the document
  935.       name will be mapped successively by each line, and what the
  936.       result will be. Checking the trace below may help clarify this.
  937.       
  938.       Run the daemon with trace from a terminal session to get trace
  939.       information
  940.       
  941.                                                                 Tim BL
  942.                                                                       
  943.   CAN'T CONNECT TO SERVER
  944.   
  945.    There is more information you can get.  use the "verbose" option on
  946.    the browser to find out what went wrong:
  947.    
  948.                         www -v http://myhost.domain:80/
  949.  
  950.    What do you get? A load of trace messages. There are several cases.
  951.    
  952.       The browser can't look up the name of the host. If it can, it
  953.       will display "Parsed address as" message. If not, try fixing
  954.       your name server or /etc/hosts file, or quoting the IP number of
  955.       the host in decimal notation (like 128.141.77.45) instead.
  956.       
  957.       The browser can get to the host but gets "Connection refused"
  958.       status back .
  959.       
  960.       Your browser gets an error number but prints "error message not
  961.       translated". This is because when it was compiled on your
  962.       platform it didn't know what form the error message table took.
  963.       Try the same thing form a unix platform for example.
  964.       
  965.       You get some network error like "network unreachable". Depending
  966.       on whether the IP network is your responsibility or not, and
  967.       your attitude to life, either fix it,  try again in an hour's
  968.       time, or complain to someone.
  969.       
  970.    _________________________________________________________________
  971.    
  972.                                                                 Tim BL
  973.                                                                       
  974.   "CONNECTION REFUSED"
  975.   
  976. The browser tries to connect to the daemon but gets this status in the
  977.                                                                 trace.
  978.                                                                       
  979. This means that noone was listening on that port number. Check the por
  980. t numbers match btween server and client.  Make sure you specify the p
  981.                 ort number explicitly in the document address for www.
  982.                                                                       
  983. If you are running the daemon without the inet daemon, (with the -a op
  984.  
  985. T. Berners-Lee                                                       17
  986.  
  987.                                  WWW Server Guide)        14 July 1993
  988.  
  989. tion) then try running it from the terminal with -v as well.  The trac
  990. e for the server should say "socket, bind and listen all ok". If it do
  991. es, and you still get "connection refused", then you must be talking t
  992.  o the wrong host (or, conceivably, different ethernet adapters on the
  993.                                                             same host)
  994.                                                                       
  995.  If you are running with the inet daemon, then check both the services
  996. file (/etc/service) or database (yellow pages, netinfo) if your system
  997.  uses it,  and the /etc/inetd.conf file. Check the service name matche
  998.                                                   s between these two.
  999.                                                                       
  1000. Did you remember to kill -HUP the inet daemon when you changed the int
  1001.                                                          ed.conf file?
  1002.                                                                       
  1003. Try running the deamon from a shell window to see what happens better.
  1004.                                                                 Tim BL
  1005.                                                                       
  1006.   YOU GET AN EMPTY DOCUMENT
  1007.  The document sent back is empty, but there is no error message.
  1008.  The inet daemon has started a process to run your server but it
  1009.  immediately failed.  Possibilities include:
  1010.  
  1011.       The daemon may not be in the file specified, or may not be
  1012.       executable by the specified user (or, if a user id is not
  1013.       specified in your variety of inetd.conf, root)
  1014.       
  1015.       You have written your own daemon and it crashes.
  1016.       
  1017.       You are using ours and it crashes (mail us!)
  1018.       
  1019.  Try running the daemon from a terminal window to see what happens.
  1020.  
  1021.                                                                 Tim BL
  1022.                                                                       
  1023.   BAD OUTPUT FROM THE DAEMON
  1024.   
  1025.                                                  These are some ideas:
  1026.                                                                       
  1027.       Try running the server from the terminal .
  1028.       
  1029.       Check the HTML source the daemon produces with
  1030.       
  1031.         www -source http://myost.domain:80/
  1032.  
  1033.       Try telnetting to the daemon and simulating the client:
  1034.       
  1035.  
  1036.         > telnet myhost.domain 80
  1037.         Connected to myhost.domain on port 80
  1038.         Escape is ^[
  1039.         GET /documentname
  1040.  
  1041.  
  1042.  
  1043. T. Berners-Lee                                                       18
  1044.  
  1045.                                  WWW Server Guide)        14 July 1993
  1046.  
  1047.                                                                 Tim BL
  1048.                                                                       
  1049.   TELNETTING TO A SERVER
  1050.   
  1051. Most implementations of telnet allow you to specify a port number. Und
  1052. er unix this is often just a second parameter, under VMS a /PORT optio
  1053.                                                                     n.
  1054.                                                                       
  1055. The HTTP protocol is a telnet protocol, so you can simulate it just by
  1056.  typing things in.  This will help you to see exactly what a sending b
  1057. ack, and it will check you that it really is the server not the browse
  1058.                                                 r which has a problem.
  1059.                                                                       
  1060.             Here is an example. (You type "telnet..." and  "GET ...").
  1061.                                                                       
  1062.         > telnet myhost.domain 80
  1063.         Connected to myhost.domain on port 80
  1064.         Escape is ^[
  1065.         GET /documentname
  1066.         <PLAINTEXT>
  1067.         Document name "/documentname" invalid.
  1068.  
  1069.   RUNNING UNDER SHELL
  1070.  You don't have to run the daemon under the inted if it doesn't work.
  1071.  You can run it from a shell session.
  1072.  If the daemon is httpd, then run it from your terminal, with a
  1073.  different port number like 8000.  You use the -p option .
  1074.  
  1075.                 httpd -p 8000
  1076.  
  1077.  Note: You must be root (under VMS, have some privilege) to run with a
  1078.  port number below 1024.
  1079.  If you select a port above 1024, then you can run as a normal user.
  1080.  This way, anyone can publish files on the net. Howeever, it isn't
  1081.  very reliable, as your server will not automatically come back up if
  1082.  the machine is rebooted. In the long term it is best to install it
  1083.  under "inetd".
  1084.  You can't use a port number which has been used by a daemon process
  1085.  recently, so you may have to switch port number if you ^C and restart
  1086.  the daemon.  When it is running like this, you can read the trace
  1087.  messages and use a debugger on it if necessary. (See also: telnetting
  1088.  to the server )
  1089.  
  1090.     Debugging using Trace
  1091.  If you can't understand why a server refuses to give back a document,
  1092.  then run wiith the -v option to get trace.  You will see the daemon
  1093.  setting up the rules for translating requests into local URLs, and
  1094.  you will see its attept to access the file (assuming you map requests
  1095.  onto files).
  1096.  
  1097.                 httpd -v -p 8000
  1098.  
  1099.  Try to access the document from a client using another terminal
  1100.  
  1101. T. Berners-Lee                                                       19
  1102.  
  1103.                                  WWW Server Guide)        14 July 1993
  1104.  
  1105.  window. Look at the trace printout.  It will probably explain what is
  1106.  happening.  If it includes specific messages below, follow them to
  1107.  detailed help.
  1108.  
  1109.       Can't find internet hostname `'
  1110.       
  1111.  If you still can't figure out the problem, mail your local guru help
  1112.  desk or if desperate www-request@info.cern.ch ENCLOSING a copy of
  1113.  that trace.
  1114.  
  1115.     Even simpler
  1116.  For testing a daemon very simply, without using a client, you can
  1117.  make the terminal be the client.  With httpd, or if the server is a
  1118.  shell script "myserver", try just running it with the terminal and
  1119.  typing GET /documentname into its input:
  1120.  
  1121.                         > httpd
  1122.                         GET /
  1123.  
  1124.  Try it with the -v option if what comes back isn't a formatted
  1125.  document.
  1126.  
  1127.                                                                 Tim BL
  1128.                                                                       
  1129. The basic W3 server:  Internals
  1130.  
  1131.  This describes the generic hypertext daemon (server) program. The
  1132.  daemon is part of the WWW project. See also:
  1133.  
  1134.       User guide .
  1135.       
  1136.       Bugs and Features
  1137.       
  1138.       Other servers
  1139.       
  1140.  The hypertext daemon, like the ftp daemon, is a program which
  1141.  responds to an incomming tcp connection and provides a service to the
  1142.  caller.
  1143.  
  1144.   SOURCES
  1145.  A compilation option (SELECT) controls whether more than one
  1146.  connection can be handled at a time. This is a function of whether
  1147.  the TCP/IP implementation beneath the application has a working
  1148.  "select()" routine. If  it is not true, this implementation services
  1149.  one connection, then drops it before accepting another one. In
  1150.  neither case does the daemon concurrently serve two clients, nor does
  1151.  it fork off a process to do that.
  1152.  The basic server loop is in the file HTDaemon.c .  A separate module
  1153.  ( for example HTRetrieve.c ) contains the code to handle one request.
  1154.  Various specific versions of this may be written for different
  1155.  flavours of server. Also used are various modules of WWW common code.
  1156.   The httpd released from CERN uses almost the entire W3 library and
  1157.  
  1158.  
  1159. T. Berners-Lee                                                       20
  1160.  
  1161.                                  WWW Server Guide)        14 July 1993
  1162.  
  1163.  can therefore access any object which a browser running on that
  1164.  machine can access, and return it as HTML or some other format.
  1165.  
  1166.                                                                 Tim BL
  1167.                                                                       
  1168. Bugs and Improvements needed
  1169.  
  1170.  Improvements to be made in the HTTP daemon program are as follows.
  1171.  (Se also Features )
  1172.  
  1173.       Call shell scripts to perform searches on directory trees or
  1174.       documents.
  1175.       
  1176.       The HTRetrieve() routine ought to be able to pick up the user
  1177.       node and userid, etc...
  1178.       
  1179.       Ought to have chroot option. (wwwww July 93)
  1180.       
  1181.                                                                 Tim BL
  1182.                                                                       
  1183. Daemon features: Update history
  1184.  
  1185.  History list for the WWW daemon . (See also bugs ).  Many other
  1186.  changes to the daemon are in fact changes to the common code library.
  1187.  
  1188.   2.06  7 JUNE 93
  1189.   
  1190.       Bug fix: Load error 500 returned as proper HTTP status, not as
  1191.       simple document.
  1192.       
  1193.       WAIS gateway now caches source files again.
  1194.       
  1195.       Bug fix: Daemon used to try to display graphics file locally on
  1196.       the server when the client couldn't display them!  Cause of much
  1197.       confusion  :-)
  1198.       
  1199.   2.05
  1200.   
  1201.       Big bug fix in local file directory handling .. didn't work in
  1202.       2.04!
  1203.       
  1204.   2.04  28 APRIL 93
  1205.   
  1206.       With the properly compiled libwww library, this daemon will
  1207.       operate as a WAIS, news etc gaetway if so configured.
  1208.       
  1209.       WAIS gateway operation bug fix.
  1210.       
  1211.   2.03-BETA: UNRELEASED
  1212.   
  1213.       Bug fix: operation with no rule file didn't work as expected.
  1214.       
  1215.  
  1216.  
  1217. T. Berners-Lee                                                       21
  1218.  
  1219.                                  WWW Server Guide)        14 July 1993
  1220.  
  1221.   2.02-BETA: 17 MARCH 93
  1222.   
  1223.       Misleading error trace removed.
  1224.       
  1225.       Compiled on HP, SGI, Sun, DEC, NeXT and binaries available
  1226.       
  1227.       Binary handling fixed in library.
  1228.       
  1229.       Reference to missing HTDirRead.h removed.
  1230.       
  1231.       Assumes that user can handle files of unknown format
  1232.       (application/binary).
  1233.       
  1234.   2.00-ALPHA  15 MAR 93
  1235.   
  1236.       Simple command line -- with no parameters, exports the /Public
  1237.       directory.
  1238.       
  1239.       Multiformat handling -- see library changes for 2.0.  Links to
  1240.       .multi filenames resolve to any file with same root, any
  1241.       recognised extension.
  1242.       
  1243.   UNREALEASED 0.9B
  1244.   
  1245.       Bug fix: If a PASS or FAIL line in the configuration file acted
  1246.       on a single document id (ie no wildcard) then it crashed the
  1247.       daemon. (HTRules.c, 17-Jun-92, TBL).
  1248.       
  1249.   SEPT 1991 V0.3
  1250.   
  1251.       Bug fix: Plain text files were returned to be parsed as SGML,
  1252.       causing them to come out as garbage. (Mike Sendall)
  1253.       
  1254.   AUGUST 1991 V 0.2
  1255.   
  1256.       -R option now suppresses default rule file.
  1257.       
  1258.       Rule file format changed completely. Now allows authorisation of
  1259.       specific paths only.
  1260.       
  1261.   JUNE 1991 VERSION 0.1
  1262.   
  1263.       -r and -R options for rules
  1264.       
  1265.       Default address is now for Inet daemon working. (29 June)
  1266.       
  1267.       -l option to log to a file.
  1268.       
  1269.       -a option for address other than default
  1270.       
  1271.  _________________________________________________________________
  1272.  
  1273.                                                                 Tim BL
  1274.  
  1275. T. Berners-Lee                                                       22
  1276.  
  1277.                                  WWW Server Guide)        14 July 1993
  1278.  
  1279.                                                                       
  1280.                        A SHELL SERVER FOR HTTP
  1281.                                    
  1282.  The HTTP protocol is very simple. The following is an example of a
  1283.  server program written in sh:
  1284.  
  1285. #! /bin/sh
  1286. read get docid
  1287. echo "<TITLE>$docid</TITLE>"
  1288. echo Here is the data
  1289.  
  1290.  The docid may have a trailing carriage return to be stripped off on
  1291.  some systems. You can modify that script to produce the data you
  1292.  actually want. The HTML syntax for marked-up text is fairly simple,
  1293.  but if you want just to send plain text, then just send the
  1294.  .PLAINTEXT.tag first:
  1295.  
  1296. #! /bin/sh
  1297. read get docid
  1298. sed -f txt2html.sed $docid
  1299.  
  1300.  or in csh
  1301.  
  1302. #! /bin/csh
  1303. request = ( `echo $<`)
  1304. if ($#request <2) exit
  1305. sed -f txt2html.sed $request[2]
  1306.  
  1307.  
  1308.  When you have written your script, set the execute bit and then
  1309.  configure the inet daemon to run it . A few more examples:
  1310.  
  1311.       A sh script to generate a menu for files in a directory
  1312.       
  1313.       An awk script to generate menu from a list of files .
  1314.       
  1315.       A perl script for all kinds of stuff on the ASIS server
  1316.       
  1317.       The shell script of the Hytelnet gateway
  1318.       
  1319.  If you know the perl language, then that is a powerful (if otherwise
  1320.  incomprehensible) language with which to hack together a server.
  1321.  See also a case study of mapping a database onto the web .
  1322.  All contributions to these examples welcome!
  1323.  
  1324.                                                                 Tim BL
  1325.                                                                       
  1326. Making a server
  1327.  
  1328.    Here is a run-through of what is needed to make a www server , with
  1329.    examples from a suggested server for the HEPDATA base of Mike
  1330.    Whalley . See also etiquette .
  1331.  
  1332.  
  1333. T. Berners-Lee                                                       23
  1334.  
  1335.                                  WWW Server Guide)        14 July 1993
  1336.  
  1337.    
  1338.    Basically, to make the data available, you make a server which is a
  1339.    modified version of your program. When a user follows a link to
  1340.    HEPDATA (or runs a command to jump straight there), the client
  1341.    program opens a connection to a server program on a VM machine
  1342.    (say, but could be VMS or unix). The server in turn runs your
  1343.    program.
  1344.    
  1345.    Let me just describe the essence of the changes needed so that you
  1346.    can get an idea of how much effort would be involved.
  1347.    
  1348.    The first thing you do is to make up an arbitrary naming method for
  1349.    anything which HEPDATA can display.  In this I include the welcome
  1350.    page, any menu, any article, any help text.  Typically one invents
  1351.    a hierarchical naming scheme, like
  1352.    
  1353.         /HEPDATA                        The first "welcome" menu
  1354.         /HEPDATA/HELP                   The top-level help
  1355.  
  1356.         /HEPDATA/HELP/REAC              The help on the reaction datab
  1357. ase.
  1358.  
  1359.         /HEPDATA/REAC                   The reaction database itself
  1360.  
  1361.         /HEPDATA/REAC?P+PBAR            list of reactions involving p
  1362. and pbar (?)
  1363.  
  1364.         /HEPDATA/DATA/RD125V687         Some article (say).
  1365.  
  1366.    You do this because, whereas an interactive user follows a path
  1367.    through the program, the W3 user calls the program once for each
  1368.    thing. There is no "state" information. This allows one to make a
  1369.    hypertext link to any part of the scheme and jump back in again
  1370.    later. For example, one might want to quote an article, or the
  1371.    reaction database, or a particular list of reactions.
  1372.    
  1373.    Now all you do is modify the program so that, given a name above,
  1374.    it will
  1375.    
  1376.    return the required document.  This means basically turning it from
  1377.    a sequence the user goes through into a set of conditionals to
  1378.    isolate each of the individual cases above. Apart from that, the
  1379.    data retrieval code is unchanged apart from the output formatting.
  1380.    Many of the options in fact mean mapping the name onto a fixed
  1381.    
  1382.    file's name its the searches which have to activate real code.
  1383.    
  1384.    The hypertext trick you need to use in the menus. Where an option
  1385.    is normally output to the screen, you have to tell the client what
  1386.    to ask for is the user selects that option. For example, in the
  1387.    main menu /HEPDATA you have an option which gives the help. You
  1388.    would represnt this "anchor" as
  1389.  
  1390.  
  1391. T. Berners-Lee                                                       24
  1392.  
  1393.                                  WWW Server Guide)        14 July 1993
  1394.  
  1395.    
  1396. <A NAME=4 HREF=/HEPDATA/HELP> Help </A>
  1397.  
  1398.    "Help" is all that is displayed, with some indication that it is an
  1399.    option. If the user choses (clicks a mouse on, choses by number
  1400.    depending on which client he has) then the client asks the server
  1401.    for /HEPDATA/HELP. ("A" is for "anchor", "HREF" is for "hypertext
  1402.    reference")
  1403.    
  1404.    For the index searches, it's as simple. When the server sends the
  1405.    text called /HEPDATA/REAC it also sends a special tag . This tells
  1406.    the client to enable a FIND command, or find panel etc (depending
  1407.    on the client). You don't have to do any human interface work. The
  1408.    client automatically comes back with a search coded up in the form
  1409.    /HEPDATA/REAC?P+PBAR etc. Your server in turn returns a menu (say)
  1410.    with pointers to the data which has been found.
  1411.    
  1412.    You can also put some formatting tags (like headings) which will
  1413.    make the data look really nice on a window system.
  1414.    
  1415.    _________________________________________________________________
  1416.    
  1417.                                                                 Tim BL
  1418.                                                                       
  1419.                            W3 AND HTMLTOOLS
  1420.                                    
  1421.  These tools aid managements of W3 servers, generation of hypertext,
  1422.  etc.
  1423.  
  1424.   W3 basic daemon         Part of the W3 project code.
  1425.                          
  1426.   Index search server    which is a slight modification to basic CERN
  1427.                          daemon, with a couple of scripts and WAIS
  1428.                          programs. Implements searches on entire
  1429.                          directory trees of WWW documents using WAIS
  1430.                          inverted indexing.
  1431.                          
  1432.   Gateway servers        which you can take and adapt.
  1433.                          
  1434.   Framemaker interface    There are some tar files on the anonymous
  1435.                          FTP archive on file://info.cern.ch/www/src
  1436.                          which allow FRAMEmaker to be used as a W3
  1437.                          tool. Dan Conolly, Convex. Incldues MIF HTML
  1438.                          translation.
  1439.                          
  1440.   Making HTML into TeX    We did this with the "WWW Book" to print it.
  1441.                          See the Makefile for example, and the scripts
  1442.                          html2latex.sed and sub1.sed . We wrote a
  1443.                          special introduction, but otherwise all the
  1444.                          text was hypertext from the W3 project.
  1445.                          
  1446.   Generating HTML         These are scripts for generating SGML
  1447.  
  1448.  
  1449. T. Berners-Lee                                                       25
  1450.  
  1451.                                  WWW Server Guide)        14 July 1993
  1452.  
  1453.                          hypertext from things like directory
  1454.                          listings, etc. Also, for checking and
  1455.                          correcting dubious HTML.
  1456.                          
  1457.   WP5.1 to HTML          WordPerfect 5.1 to HTML conversion
  1458.                          
  1459.   LaTex to HTML           Code from Nikos Drakos, Computer Based
  1460.                          Learning Unit, University of Leeds.
  1461.                          
  1462.   Server log analysis     Analysing server logs requires first of all
  1463.                          changing the numeric internet node numbers
  1464.                          into domain names. httpd-analyse.c is a
  1465.                          program to do that. Feed the results through
  1466.                          awk and grep of your choice!
  1467.                          
  1468.   Server log analysis     Getsites .c is a program which generates
  1469.                          reports on a weekly or monthly basis.
  1470.                          
  1471.   Web-roaming  robot etc
  1472.                           Guido van Rossum's knobot code in "Python"
  1473.                          language.
  1474.                          
  1475.   Telnet server           Setting up a service machine for anonymous
  1476.                          users to log in to a www client.
  1477.                          
  1478.   Mail Robot              A program to return any information in the
  1479.                          web information by electronic mail
  1480.                          
  1481.                                                                 Tim BL
  1482.                                                                       
  1483. HTMLGeneration
  1484.  
  1485.  Here are some example files you can use for generating HTML from
  1486.  lists of files and other things.
  1487.  
  1488.   RTF to HTML            Convert RTF (using specific styles) into
  1489.                          HTML.
  1490.                          
  1491.   fix-html.pl            written by Dan Connolly, is a perl script to
  1492.                          legitimize old HTML files into SGML-abiding
  1493.                          HTML (as per the DTD that Dan created).
  1494.                          
  1495.   text2html.sed           A sed script to turn plain text into
  1496.                          plain-looking valid HTML markup so that it
  1497.                          will be rendered just as it was.
  1498.                          
  1499.   ls2html.awk            is an awk script which will just take a list
  1500.                          of names and generate a menu.
  1501.                          
  1502.   dir2html               is a shell script which generates a menu of
  1503.                          pointers to files with particular suffixes in
  1504.                          a set of directories. It also includes a
  1505.  
  1506.  
  1507. T. Berners-Lee                                                       26
  1508.  
  1509.                                  WWW Server Guide)        14 July 1993
  1510.  
  1511.                          README file at the head of the hypertext list
  1512.                          if one exists.
  1513.                          
  1514.   htn2html.c              See the Hytelnet gateway for the program to
  1515.                          convert hytelnet data into HTML.
  1516.                          
  1517.   findrefs.pl             Written by Ari Lemmke, finds references
  1518.                          http:... in plain text files and generates
  1519.                          anchors out of them.
  1520.                          
  1521.  You can make any variations on these you like of course. [CERN does
  1522.  not accept any responsability for things quoted in these lists].
  1523.  
  1524. Updating the Newsgroup lists
  1525.  
  1526.  To update some of the news pages automatically you must be logged on
  1527.  to the news server or have the news directories mounted.
  1528.   Carl mentioned that you must be a member of the UNIX group news
  1529.  (otherwise you won't have permission to read the news directories)
  1530.  but that doesn't seem to be necessary for these functions.
  1531.  
  1532.   UPDATEGROUPS
  1533.  This script updates the list of newsgroups. For the overview list ,
  1534.  it saves everything before the "Others" heading, and adds on a list
  1535.  of pointers to newsgroup stems not already mentioned in the saved
  1536.  hypertext.
  1537.  For each stem, it saves any command before the glossary list of
  1538.  groups, and then regenerates that list of groups.
  1539.  
  1540.   NEWSPAGE_UPDATE (OLD)
  1541.  The script NewsPage_Update creates complete lists of active groups
  1542.  for the following groups: alt, bionet, bit, biz, cern, ch, comp,
  1543.  eunet, gnu, news, rec, sci, soc, talk, vmsnet. It does this by
  1544.  writing the header in explicitly for each group, and then generating
  1545.  a list of of subgroups using FindGroups
  1546.  For comp and news, a full list is placed in fullcomp.html and
  1547.  fullnews.html. The files comp.html and news.html are formatted by
  1548.  hand already, and so are not touched by the script.
  1549.  NewsPage_Update works by writing some HTML text into a file for each
  1550.  group to be updated, called [newsgroup_name].html.new, then calling
  1551.  the script FindNewsGroups.  This checks the file
  1552.  /usr/local/lib/news/newsgroups for the groups within the current
  1553.  group which are active.  Finally the new file is renamed to remove
  1554.  the .new.
  1555.  The list of stems to search, and their titles and any other comment
  1556.  is hardcoded into the NewsPage_Update script, and the list is
  1557.  DUPLICATED in Others_Update.
  1558.  
  1559.   OTHERS_UPDATE
  1560.  The Others_Update script finds stems which are not included in the
  1561.  Overview.html file, but which are active.  This list of which groups
  1562.  not to include is hardcoded into the script.  For each group, it
  1563.  
  1564.  
  1565. T. Berners-Lee                                                       27
  1566.  
  1567.                                  WWW Server Guide)        14 July 1993
  1568.  
  1569.  calls GrpCreate.  This adds the name to OtherGroups/Overview.    It
  1570.  then runs FindNewsGroups for each group.
  1571.  
  1572.     NOTE
  1573.  Once the script has completed all the .new groups must be renamed
  1574.  manually to remove the .new extension.
  1575.  
  1576.   GRPCREATE
  1577.  This reads a newsgroup stem name from stdin.
  1578.  It then creates the top of a file for the list of groups with that
  1579.  stem. This will be called ${nn}.html.new. where ${nn} is the stem
  1580.  name. Unfortunately there is no way to get a description of the stem
  1581.  to include in this file. However, if the .html file already exists,
  1582.  it will use everything up to an excluding the first DL tag from the
  1583.  .html file for the .html.new file. Therefore, everything above the DL
  1584.  tag may be hand edited.
  1585.  GrpCreate adds a pointer from OtherGroups/Overview.html.new to the
  1586.  .html file.
  1587.  The .html file is renamed .html.old, and teh .html.new becomes .html,
  1588.  with diffs being stored in a .diffs file under the date.
  1589.  
  1590. .\" Macros for HTML .\" Jim Davis 6 Nov 92 .ps 12 .in 5 .de B ..
  1591.  .de R .. .de H1 .ti -5 .ps 18 \fB\\$1\fR .ps 12 .br .. .de H
  1592. 2 .ti -3 .ps 14 \fB\\$1\fR .ps 12 .br .. .de H3 \\$1 .br ..
  1593.  .de H4 \\$1 .. .de H5 \\$1 .. .de H6 \\$1 .. .de H7 \\$1 .
  1594. . .de H8 \\$1 .. .de H9 \\$1 .. .de DL .in +5 .. .de DE .in
  1595.                 -5 .. .de DT .ti -3 * \\$1 .. .de DD .br .. 
  1596.                                                                       
  1597.  
  1598. Date: Wed, 4 Nov 1992 16:48:34 -0500
  1599. From: Jim Davis <davis@dri.cornell.edu>
  1600. To: wei@xcf.berkeley.edu, www-talk@nxoc01.cern.ch
  1601. Subject: improved printing of WWW files
  1602.  
  1603. If you can't quite manage to live without hardcopy, you may wish somet
  1604. imes to print WWW files.  I have written a couple of scripts to do thi
  1605. s.  They are particularly useful with Pei Wei's excellent Viola WWW br
  1606.                                                                 owser.
  1607.                                                                       
  1608.                          A tar archive is available for anonymous FTP:
  1609.                                                                       
  1610.                                dri.cornell.edu/pub/davis/print-www.tar
  1611.                                                                       
  1612.                                                           It contains:
  1613.                                                                       
  1614.  
  1615. README
  1616. print-www
  1617. print-www.l
  1618. html-to-latex
  1619. html2latex.sed (modified version of original CERN version)
  1620.  
  1621.  
  1622.  
  1623. T. Berners-Lee                                                       28
  1624.  
  1625.                                  WWW Server Guide)        14 July 1993
  1626.  
  1627. The hardest part was writing the perl script to obtain documents via h
  1628.       ttp protocol - turns out you cant just run pipes through telnet.
  1629.                                                                       
  1630. The conversion from HTML to LaTex is not really robust yet -  this  is
  1631.   doubly hard since there is no guarentee that the HTML is legal.  But
  1632.  at least it works for my test cases.  No doubt it will be improved in
  1633.                                                                  time.
  1634.                                                                       
  1635.                                                            best wishes
  1636.                                                                       
  1637.                            GATEWAY SOFTWARE
  1638.                                    
  1639.  See also: W3 server software , W3 client software
  1640.  These are servers which provide data extracted from other systems.
  1641.  they are built using code from the basic daemon, or scripts.
  1642.  
  1643.   FIND gateway           for CERN/VM XFIND which calls a REXX exec to
  1644.                          get the information from the XFIND system
  1645.                          running on the CERNVM mainframe.
  1646.                          
  1647.   Hytelnet gateway        A gateway to Peter Scott's list of telnet
  1648.                          sites
  1649.                          
  1650.   VMS Help gateway        This allows any VMS help files to be made
  1651.                          available to WWW clients. Runs on VAX/VMS.
  1652.                          
  1653.   WAISGate                A gateway to information available using the
  1654.                          W.A.I.S. protocol.
  1655.                          
  1656.   DCLServer               A server for VMS systems which allows you to
  1657.                          write a gateway to your own favorite
  1658.                          information system using DCL.
  1659.                          
  1660.   System33                A (big) csh script server providing data
  1661.                          including Xerox System33 documents, man pages
  1662.                          in plain text, phone numbers, etc. etc...!
  1663.                          
  1664.   Oracle                  A generic server to oracle. Could be used as
  1665.                          a basis for gateways to specific Oracle
  1666.                          databases.
  1667.                          
  1668.   Geography               Gateway to the Geography server at U
  1669.                          Michigan
  1670.                          
  1671.   TechInfo                TechInfo is the CWIS from MIT.  A gateway
  1672.                          exists thanks to Linda Murphy/Upenn.
  1673.                          
  1674.                                                                 Tim BL
  1675.                                                                       
  1676. Geography gateway
  1677.  
  1678.                                                       Wed, 18 Nov 1992
  1679.                                                                       
  1680.  
  1681. T. Berners-Lee                                                       29
  1682.  
  1683.                                  WWW Server Guide)        14 July 1993
  1684.  
  1685. Jim Davis  Here is a quickly hacked up Gateway from WWW to the Univers
  1686. ity of Michigan Geography server.  It expects one argument, a  WWW doc
  1687.  id.  It ignores the "pathname", extracts the search words, then passe
  1688. s those to the server.  It does NOT parse the data returned by the ser
  1689.  ver (that is an improvment yet to be done) but you can understand the
  1690.                                                                output.
  1691.                                                                       
  1692. To use this, you would need to have an HTTP server running someplace w
  1693.  here you can attach this gateway.  I can provide the very simple HTTP
  1694. server I use here, but this subject is already documented in the WWW o
  1695.                                                   nline documentation.
  1696.                                                                       
  1697.                                                    Source code in perl
  1698.                                                                       
  1699. The WWW TechInfo gateway
  1700.  
  1701.  This is a gateway built using the basic server code, plus one source
  1702.  file in C. Thanks to Linda Murphy of Univerity of Pennsylvania for
  1703.  the etchinfo code.
  1704.  
  1705.       The gateway data as running at CERN
  1706.       
  1707.       The source file
  1708.       
  1709.                                                                 Tim BL
  1710.                                                                       
  1711. The W.A.I.S. - WWW gateway
  1712.  
  1713.  This is an example of a WWW server and a WAIS client. It is just the
  1714.  regular httpd daeomon linked with:
  1715.  
  1716.       a version of the libwww library which was compiled with the
  1717.       DIRECT_WAIS option, and includes the HTWAIS module;
  1718.       
  1719.       the freeWAIS libraries from CNIDR.
  1720.       
  1721.  See a summary of some data available through the gateway .
  1722.  
  1723.   WSRC FILES
  1724.  The gateway keeps a cache of WAIS "source" files. These are files
  1725.  describing WAIS servers. They are normally picked up automatically by
  1726.  searching a "directory of servers" index. Once the gateway has picked
  1727.  up a desciption of  a server,  it uses the description to describe
  1728.  the server to those who follow links to it. (See the HTWSRC module of
  1729.  libwww)
  1730.  These source files are parsed, and are kept in the directory
  1731.  /usr/local/lib/WAIS under the server name, port, and database name.
  1732.  
  1733.                                                                 Tim BL
  1734.                                                                       
  1735. VMS Help server
  1736.  
  1737.  This server can provide WWW users with any information stored in VMS
  1738.  
  1739. T. Berners-Lee                                                       30
  1740.  
  1741.                                  WWW Server Guide)        14 July 1993
  1742.  
  1743.  Help format.
  1744.  
  1745.     Additional information available:       :->
  1746.     
  1747.   Try me !               An example server running at CERN
  1748.                          
  1749.   Status                 The current state, pointers to more
  1750.                          information
  1751.                          
  1752.                                                                    JFG
  1753.                                                                       
  1754.   GATEWAY TO VMS HELP: INTERNALS
  1755.   
  1756.    These are technical and installation notes about the gateway to VMS
  1757.    Help . Please send bug reports and suggestions to Jean-Francois
  1758.    Groff (jfg@cernvax.cern.ch).
  1759.    
  1760.     Sources
  1761.     
  1762.    The program consists of the generic daemon HTDaemon.c , and a
  1763.    special function, stored in VMSHelpGate.c , to retrieve VMS Help
  1764.    data and convert it to HTML.
  1765.    
  1766.     Installation
  1767.     
  1768.    The files you need are as follows. You should customise them,
  1769.    putting in your own directory names.:
  1770.    
  1771.   launchgate.com         Runs the server as a detached process. Put a
  1772.                          call to this from your sys$startup procedure,
  1773.                          wherever that is. This detaches a job to use
  1774.                          www_server.com ans input, and a log file as
  1775.                          output.
  1776.                          
  1777.   www_server.com         The server command file, a wrapper for the
  1778.                          actual server executable.  In this file, set
  1779.                          the temporary directory for the storage of a
  1780.                          cache of .HLP files. This file runs the
  1781.                          executable.
  1782.                          
  1783.   test.com               Here is just an example of  a file to build
  1784.                          and test the server.
  1785.                          
  1786.   descrip.mms            This is an MMS file to build the executable.
  1787.                          If you don't have MMS, you may be able to
  1788.                          figure out from loking at it which commands
  1789.                          you should use.  You can find a machine
  1790.                          running MMS and generate the equivalent .com
  1791.                          files. See comments at the top of this file
  1792.                          on how to run it.
  1793.                          
  1794.    The source files and executable .EXE are currently (October 92)
  1795.  
  1796.  
  1797. T. Berners-Lee                                                       31
  1798.  
  1799.                                  WWW Server Guide)        14 July 1993
  1800.  
  1801.    available on HEP  decnet in vxcrna::disk$d1:[jfg.www...].  Note
  1802.    also you can pick up the master sources from dxcern:: automatically
  1803.    by running
  1804.    
  1805.    MMS /MACRO=(U=DXCERN::).
  1806.    
  1807.    If you are not in HEP decnet, you should find the sources in the
  1808.    WWWDaemon_v.vv.tar.Z file in the distribution. See the README file.
  1809.    
  1810.    _________________________________________________________________
  1811.    
  1812.                                                                    JFG
  1813.                                                                       
  1814.   VMS HELP SERVER BUGS
  1815.   
  1816. This is a list of known bugs and desired improvements. Don't let it sh
  1817. rink too fast : send your bug reports and suggestions to Jean-Francois
  1818.                                           Groff (jfg@cernvax.cern.ch).
  1819.                                                                       
  1820.       The keyword search works fine on any number of levels down, but
  1821.       then the generic daemon doesn't know how deep the server went,
  1822.       so anchor names lack the intermediate levels. Solution :
  1823.       generate anchor names relative to the input path (before '?').
  1824.       
  1825.       DANGER : Attempts to access VMS topics with a weird name like
  1826.       ":=" will crash the server because VMS will try to create a .HLP
  1827.       file with an invalid file specification due to these special
  1828.       characters. Solution : Make a good escaping system (that works
  1829.       with VMS and Un*x styles as well). Crude and bulletproof
  1830.       solution : Ignore any offending topic name !
  1831.       
  1832.       Reference to another help library through @ will only search
  1833.       SYS$HELP for the corresponding .HLB file.
  1834.       
  1835.       We need an overview page that lists all help libraries
  1836.       available.
  1837.       
  1838.         __________________________________________________________ JFG
  1839.                                                                       
  1840.   VMS HELP SERVER FEATURES
  1841.   
  1842.    This lists the main features of the VMS Help gateway, with
  1843.    improvements in reverse chronological order. Help make it grow fast
  1844.    : send your bug reports and suggestions to Jean-Francois Groff
  1845.    (jfg@cernvax.cern.ch).
  1846.    
  1847.     Experimental gateway 0.4 -- 2 Oct 91
  1848.     
  1849.       Accepts user queries by number or by name. In the latter case,
  1850.       can go down several levels, for instance, from the main help
  1851.       page : "cc /lib" will go to topic CC, subtopic /LIBRARY.
  1852.       
  1853.  
  1854.  
  1855. T. Berners-Lee                                                       32
  1856.  
  1857.                                  WWW Server Guide)        14 July 1993
  1858.  
  1859.       On invocation with only //node:port/HELP, displays the contents
  1860.       of the standard VMS Help library SYS$HELP:HELPLIB.HLB (function
  1861.       lis_to_html).
  1862.       
  1863.       Address format : //node:port/HELP/[@library/][topic[/subtopic]*]
  1864.       
  1865.    __________________________________________________________
  1866.    
  1867.                                                                    JFG
  1868.                                                                       
  1869.                              STYLE GUIDE
  1870.                                    
  1871.  This guide is designed to help you create a hypertext database
  1872.  effectively communicates your knowledge to the reader.  It has been
  1873.  prepared in the light of comments by readers, and many demands by
  1874.  providers of online documentation.   Some of the points made may be
  1875.  influenced by personal preference, and some may be common sense, but
  1876.  a collection of points has been demanded, and so here it is.
  1877.  The guide is designed to be read sequentially, but feel free to
  1878.  depart from this.  The sections are as follows:
  1879.  
  1880.       Introduction
  1881.       
  1882.       Overall structure of your work
  1883.       
  1884.       Within each document
  1885.       
  1886.       Test your document
  1887.       
  1888.       Background reading
  1889.       
  1890.       Reader comments
  1891.       
  1892. This document is open to comment
  1893.  
  1894.  Suggestions are strongly invited, if you think of anything mail it to
  1895.  timbl@info.cern.ch, mentioning the Style Guide for Online Hypertext
  1896.  or its URL.
  1897.  
  1898.                                                                 Tim BL
  1899.                                                                       
  1900. Introduction
  1901.  
  1902.  You are going to write (or generate ) some online hypertext. Because
  1903.  hypertext is potentially unconstrained you are a little daunted. Do
  1904.  not be. You can write a document as simplly as you like.  In many
  1905.  ways, the simpler the better.
  1906.  You will be writing a number of separate files.  These files will be
  1907.  linked to each other, and to external documents, to make your final
  1908.  work.
  1909.  You may think of your work as a "document", and if it were on paper,
  1910.  then you would call it that.  In the online case though, we tend to
  1911.  refer to each individual file as a document. A  document may
  1912.  
  1913. T. Berners-Lee                                                       33
  1914.  
  1915.                                  WWW Server Guide)        14 July 1993
  1916.  
  1917.  correspond, in the book analogy, to a section or a subsection, or
  1918.  even a footnote. In this guide, we'll refer to the whole collection
  1919.  as a work.
  1920.  The document is the unit by which information is picked up.  At any
  1921.  one time, a document is completely loaded into the reader's computer.
  1922.  It is also normally the amount you edit at any one time, though with
  1923.  a good editor you will probably have a number of documents open at a
  1924.  time.
  1925.  The section on structure discusses how you organize your material
  1926.  into documents.   Another section discusses how to organise your
  1927.  material within a document .
  1928.  (Up to overview ,  on to structure )
  1929.  
  1930.                                                                 Tim BL
  1931.                                                                       
  1932. Structure
  1933.  
  1934.  If you have in mind a body of information to put across to your
  1935.  reader, you probably have a mental organisation for it.  Normally
  1936.  this is a sort of hierarchical tree, like the chapters of a book if
  1937.  you were to write a book.
  1938.  Keep this structure.  It helps readers to have a tree structure as a
  1939.  basis for the book: it gives them a feeling of knowing where they
  1940.  are.   You can also us this structure for oganising your files in
  1941.  directories.
  1942.  You should also bear in mind:
  1943.  
  1944.       The reader's preconceived structure
  1945.       
  1946.       The idea of overlapping trees
  1947.       
  1948.       How big to make each document
  1949.       
  1950.  (Up to overview , back to Introduction, on to: writing each document)
  1951.  
  1952.                                                                 Tim BL
  1953.                                                                       
  1954.   THE READER'S STRUCTURE .
  1955.  Remember always the audience for whom you are writing.  If they are
  1956.  novices in the subject,  it will normally help if you are firm about
  1957.  the structure of your work, so that they can learn the structure of
  1958.  the knowledge itself.   For example, if you feel that the subject
  1959.  falls into three distinct areas, then that is an importnat thing to
  1960.  teach.
  1961.  If, however, your readers will already have some knowledge in the
  1962.  subject, then they will already have formed their own structure for
  1963.  it.  In this case they will conciously or subconsiouly know where
  1964.  they expect to find things. If your structure is different from
  1965.  theirs,  enforcing it too strongly will confuse them and put them
  1966.  off.
  1967.  You may in this case have resist a strong tendency to put across your
  1968.  own structure strongly and to the detriment of all others.  There are
  1969.  
  1970.  
  1971. T. Berners-Lee                                                       34
  1972.  
  1973.                                  WWW Server Guide)        14 July 1993
  1974.  
  1975.  two solutions.
  1976.  If you have a single well-defined audience in mind, who will share a
  1977.  similar world view, then try to write excatly for that world view
  1978.  rather than yours.
  1979.  If you are simultaneously writing for more than one group, then you
  1980.  must provide for both.
  1981.  When you make a reference,  qualify it  with a clue to allow soime
  1982.  people to skip it. For example, "If you really want to know how it
  1983.  works inside, see the Internals guide", or "A step-by-step
  1984.  introduction is in the tutorial".
  1985.  Provide links for both reader's views. Your work will be more
  1986.  connected than a simple tree, but with proper qualifiaction, noone
  1987.  should get lost.
  1988.  Provide two sepate tree "roots". For example, you can write a
  1989.  step-by-step tutorial  and a functionaly direct reference tree for
  1990.  the same data. Both will at the lowest level have the same data, but
  1991.  while the first will deal with the simple things first, the second
  1992.  may be functionnaly grouped.   This is just like having several
  1993.  indexes to a book.  The tutirial might also include information which
  1994.  the reference work does not.
  1995.  
  1996.  (Up to overview , back to Introduction , on to: writing each document
  1997.  )
  1998.  
  1999.                                                                 Tim BL
  2000.                                                                       
  2001.   OVERLAPPING TREES
  2002.  Here is an example of a work (describing some programming functions,
  2003.  say) with two separate structures:
  2004.  
  2005.                         Tutorial                        Reference
  2006.                            |                                |
  2007.                   Let's do it togther                  ---------------
  2008. --
  2009.                 from simple to difficult              |
  2010. |
  2011.                             |                   by Functional      Alp
  2012. habetical
  2013.                             |                       group            b
  2014. y name
  2015.                   Task oriented examples              |
  2016. |
  2017.                             |                          ---------------
  2018. --
  2019.                             |                               |
  2020.                   Examples of use of               Syntax definition f
  2021. or
  2022.                   specific functions   <-------->    specific function
  2023. s
  2024.  
  2025.  The novice user starts at the top left, and works his way down. Where
  2026.  he needs specific details, he will get down to the examples and from
  2027.  
  2028.  
  2029. T. Berners-Lee                                                       35
  2030.  
  2031.                                  WWW Server Guide)        14 July 1993
  2032.  
  2033.  them a link to the underlying definitive desctiptions of each. As far
  2034.  as he is concerned, he is reading a tree-strucured work.   In fact,
  2035.  he is reading the same information as the expert who, coming in to
  2036.  check on one particular function, then looks up an example of its
  2037.  use.
  2038.  (Up to structure , back to user's structure , on to: document size )
  2039.  
  2040.                                                                 Tim BL
  2041.                                                                       
  2042.   HOW BIG TO MAKE EACH DOCUMENT
  2043.  The most important point here is that a document should put across a
  2044.  well-defined concept.  It is not generally worth splitting one idea
  2045.  arbitrarily into two bits in order to make the bits smaller.  Nor is
  2046.  it a good idea to put together ideas which area really separate just
  2047.  to make a bigger document.
  2048.  A document can be as small as a footnote .
  2049.  There are two upper limits on a document's size.  One is that long
  2050.  documents will take longer to transfer, and so a reader will not be
  2051.  able to simply jump to it and back as fast as he or she can think.
  2052.  This depends a lot on the link speed of course.
  2053.  The other limit is the difficulty for a reader to scroll through
  2054.  large documents. Readers with character based terminals don't general
  2055.  read more than a few screens.  They often only absorb what is on the
  2056.  first screen, as if that is not interesting they won't be bothered to
  2057.  scroll down.  Readers are also put off by being left at the top of a
  2058.  large document.
  2059.  Readers with graphic interfaces generally scroll through long
  2060.  documents with a scroll bar.   When the scroll bar is moved a small
  2061.  amount, the document should move a sufficiently small amount so that
  2062.  some of the original window-full is still left in the window.  This
  2063.  allows the reader to scan the document. If the document is any
  2064.  bigger, then it is basically unreadable, in that any movement of the
  2065.  scroll bar will loses the place and leaves the reader disoriented.
  2066.  Advantages with longer documents are that it is easier for readers
  2067.  with scrollbars to read through in an uninterrupted flow, if that is
  2068.  how the document is written.
  2069.  Also,  one doesn't have to go to the trouble of making (or
  2070.  generating) so many links and keeping them up to date if things are
  2071.  altered.  If making the links is a problem, just settle for one link
  2072.  to a contents page.  Some browsers have "next" and "previous" buttons
  2073.  to allow a document to be browsed serially according to a list.
  2074.  (In fact, one can normally scroll up and down explicitly page by
  2075.  page, but this is gives the same feeling as the terminal interface.)
  2076.  A rough guide, then, for the size of a document is:
  2077.  
  2078.       For online help, menus giving access to other things: small
  2079.       enough to fit on 24 lines.  Check this by using a terminal
  2080.       browser.
  2081.       
  2082.       For textual documents, of the order of half a letter-sized (A4)
  2083.       page to 5 pages.
  2084.       
  2085.  
  2086.  
  2087. T. Berners-Lee                                                       36
  2088.  
  2089.                                  WWW Server Guide)        14 July 1993
  2090.  
  2091.  (Up to structure , back to overlapping trees , on to: within each
  2092.  document )
  2093.  
  2094.                                                                 Tim BL
  2095.                                                                       
  2096. Within each document
  2097.  
  2098.  This section of the style guide deals with the layout of text within
  2099.  a "document", the unit of retrieval of information on the web.
  2100.  To be completed.
  2101.  You should try to:
  2102.  
  2103.       Sign your work
  2104.       
  2105.       Give its status
  2106.       
  2107.       Make links into context .
  2108.       
  2109.       Use context-free document titles
  2110.       
  2111.       Format device-independantly
  2112.       
  2113.       Write for the printed work too
  2114.       
  2115.       Write readable text despite the links
  2116.       
  2117.  (up to overview , back to structure , on to testing )
  2118.  
  2119.                                                                 Tim BL
  2120.                                                                       
  2121.   SIGN IT!
  2122.  An important aspect of information which helps keep it up to date is
  2123.  that one can trace its author.  Doing this with hypertext is easy --
  2124.  all you have to do is put a link to a page about the author (or
  2125.  simply to the author's phone book entry).
  2126.  Make a page for yourself with your mail address and phone number. At
  2127.  the bottom of files for which you are responsible, put a small note
  2128.  -- say just your initials -- and link it to that page. The address
  2129.  style (typically right justified) is useful for this.
  2130.   Your author page is also a convenient place to put and disclaimers,
  2131.  copyright noitices, etc which law or convention require. It saves
  2132.  cluttering up the mesages themselves with a long signature.
  2133.  If you are using the NeXT hypertext editor, then you can put this
  2134.  link from your default blank page so that it turns up on the bottom
  2135.  of each new document.
  2136.  ( up , back to ..., on to  giving your document's status)
  2137.  
  2138.   THE STATUS OF YOUR DOCUMENT
  2139.  Some information is definitive, some is hastily put together and
  2140.  incomplete. Both are useful to readers, so do not be shy to put
  2141.  information up which is incomplete or out of date -- it may be the
  2142.  best there is. However, do remember to state what the status is. When
  2143.  was it last updated? Is it complete? What is its scope? For a phone
  2144.  
  2145. T. Berners-Lee                                                       37
  2146.  
  2147.                                  WWW Server Guide)        14 July 1993
  2148.  
  2149.  book for example, what set of people are in it?
  2150.  Not every document needs a status declaration, if  there is something
  2151.  in the overview page of the work which covers it.
  2152.  You can of course also give a feel for the status of the text by its
  2153.  language ... bad spelling, missing capitals, and relaxed grammer all
  2154.  indicate informal notes.     Careful use of verbs such as "shall" and
  2155.  "should", and the introduction of Long Capitalised Noun Phrases
  2156.  (LCNPs) will give at least the impression of an ISO standard.  ;-)
  2157.  
  2158.     Date it
  2159.  In some cases it can be useful to put creation dates and last
  2160.  modified dates on your work.  (Note that this is the sort of thing
  2161.  which one could make a server do automatically with a little
  2162.  programming).
  2163.  Figure out whether putting one might later save the reader from
  2164.  following out of date information.
  2165.  (back to Sign It, On to links into context )
  2166.  
  2167.   LINKING TO CONTEXT
  2168.  A major difference between writing part of a serial text, and an
  2169.  online document, is that your readers may have jumped in from
  2170.  anywhere.   Even though you have only made links to it from one
  2171.  place, any other person may want to refer to that particular point,
  2172.  and will so make a link to that particular part of your work from
  2173.  their own. So  you can't rely on your reader having followed your
  2174.  path through your work.
  2175.  Of course if you are writing a tutorial, it will be important to keep
  2176.  the flow from one document to the next in the order you intended for
  2177.  its primary audience.   You may not wish to cater specially for those
  2178.  who jump in out of the blue, but it is wise to leave them with enough
  2179.  clues so as not to be hopelessly lost. Some ways of doing this are:
  2180.  
  2181.       Watch that your text and vocabulary stands by itself. Starting a
  2182.       document with "The next thing we we consider is..." or "The only
  2183.       solution to this problem is..." will certainly confuse.
  2184.       
  2185.       Sometimes the opening words refer to the context, and can be
  2186.       linked to background information.   For example, in the WWW
  2187.       project documentation, the first occurence of the acronym WWW is
  2188.       often linked back to the central project document.
  2189.       
  2190.       The navigation hints at the top or bottom of the document can
  2191.       give explicit pointers.  Examples are at the bottom of this
  2192.       document.
  2193.       
  2194.  It can also be useful to imagine as you are writing that  you
  2195.  yourself may wish to reuse the document. some day.
  2196.  (Part of style guide for online hypertext . Up to Writing each
  2197.  document , on to Title tag)
  2198.  
  2199.                                                                 Tim BL
  2200.                                                                       
  2201.  
  2202.  
  2203. T. Berners-Lee                                                       38
  2204.  
  2205.                                  WWW Server Guide)        14 July 1993
  2206.  
  2207.   DEVICE INDEPENDENCE
  2208.  The hypertext you write is stored in HTML language, which does not
  2209.  contain information about the fonts and paragraph shapes and spacing
  2210.  which should be used for displaying the document.
  2211.  This gives great advantages in that your document will be rendered
  2212.  successfully on whatever platform it is viewed, including a plain
  2213.  text terminal.
  2214.  You should be aware that different clients do use different spacing
  2215.  and fonts.   You should be careful to use the structuring elements
  2216.  such as headers and lists in the way in which they were intended.  If
  2217.  you don't like the rendering on your particular client, don't try to
  2218.  fix it by using inappropriate elements, or trying for example to
  2219.  force extra spacing with empty elements.  This may well end up being
  2220.  interpreted differently by other clients and looking very strange.
  2221.  You can in many cases configure the client displays each element.
  2222.  For example:
  2223.  
  2224.       Always use heading levels in order, with one heading level 1 at
  2225.       the top of the document, and if necessary several level 2
  2226.       headings, and then if necessary several level 3 headings under
  2227.       each level 2 heading.  If you don't like the way heading level 2
  2228.       is formatted, fix it on your client, don't just skip to heading
  2229.       level 3.
  2230.       
  2231.       Don't put extra spaces or blank lines into your text to pad it
  2232.       out, except in preformatted (PRE) sections.
  2233.       
  2234.       Don't refer in your text to facets of particular browesrs.
  2235.       Asking someone to "click here" won't make sense without a mouse,
  2236.       just as asking someone to "select a link by number" will betray
  2237.       the fact that you were using the line mode browser.  Just leave
  2238.       a link.  The instructions get boring as the user will normally
  2239.       know how to select a link.
  2240.       
  2241.  See also: testing your document .
  2242.  Following these guidelines you may find that the end result does not
  2243.  appear on your screen exactly as you would like, but your readers
  2244.  will probably be happier.
  2245.  (Part of the Style Guide for Online Hypertext .  Up to within each
  2246.  document , back to , on to printable hypertext)
  2247.  
  2248.                                                                 Tim BL
  2249.                                                                       
  2250.   PRINTABLE HYPERTEXT
  2251.  In an ideal world, paper might not be necessary.  In a next to ideal
  2252.  world, one would have enough time to write a hypertext version of a
  2253.  document and also a completely reauthor a paper version.  In the real
  2254.  world, you wilkl probably want to generate any printed documents and
  2255.  online documents from the same file.
  2256.  Suppose the HTML files will be the master, and you will generate the
  2257.  printable from this, by translation into TeX, etc.
  2258.  If you might one day want to do this, try to avoid references in the
  2259.  text to online aspects.  "See the section on device independence" is
  2260.  
  2261. T. Berners-Lee                                                       39
  2262.  
  2263.                                  WWW Server Guide)        14 July 1993
  2264.  
  2265.  better than "For more on device independence, click here.".  In fact
  2266.  we are talking about a form of device independence.
  2267.  Unfortunately the recommended practices of signing each document and
  2268.  giving navigational links  tend to mess up the printable copy, though
  2269.  one can of course develop ways of stripping them out if they follow a
  2270.  common format.
  2271.  (Up to:  within each document;  back to device independece, on to
  2272.  ...)
  2273.  
  2274.                                                                 Tim BL
  2275.                                                                       
  2276. Test your document
  2277.  
  2278.  In a way your hypertext is like a book, which you should have
  2279.  proof-read. In a way, it is like a program which you should have
  2280.  tested.  At least get someone from the group for which you wrote the
  2281.  document to read it and give you some feedback.  Other ideas are:
  2282.  
  2283.       Read the document several different client programs, to ensure
  2284.       that you have formatted it in a device independent way.
  2285.       
  2286.       Monitor the readership of your document. You can do this by
  2287.       analysing the server log files .    You may find that some parts
  2288.       are not being read, perhaps because people are looking in the
  2289.       wrong place for them.  You may see that people often follow a
  2290.       path and backtrack. If you can guess what they were looking for,
  2291.       you can make the clues around the link more helpful.  (Remember
  2292.       to keep log information confidential until you have removed user
  2293.       information from it.)
  2294.       
  2295.       Make it clear whether your will accept criticism or suggestions
  2296.       from your readers, and how they should send it.
  2297.       
  2298.       Ask people to solve problems using the document, and report on
  2299.       their success. If they fail, find out what they were looking
  2300.       for, whether it was in the document at all,
  2301.       
  2302.   HOW MUCH TESTING?
  2303.  Testing takes time.    The decision of how  much testing you do is
  2304.  based on the quality of the document you wish to provide.  You are
  2305.  balancing your reader's time and effort against yours.   If your
  2306.  document is "selling" an idea, or if you are selling the document or
  2307.  providing a service, you will want  to make it as easy as possible
  2308.  for the reader.   If many people will read your work, a little of
  2309.  your time will save a lot of theirs.
  2310.  If however you are documenting some obscure part of a system in which
  2311.  no one other than yourself is likely to be interested,  or if you
  2312.  feel that your readers are lucky to have anything available at all,
  2313.  there is no point wasting time testing it.  In the event of someone
  2314.  needing the information, they might have to go to some extra trouble
  2315.  to follow several links to find what they want, and then to
  2316.  understand what you have written.  This may be the most efficient way
  2317.  
  2318.  
  2319. T. Berners-Lee                                                       40
  2320.  
  2321.                                  WWW Server Guide)        14 July 1993
  2322.  
  2323.  of working.  I emphasize this because there is very much information
  2324.  which is for a fleeting moment in people's minds, or is hastily
  2325.  scribbled down on some file, and which may be important to posterity.
  2326.   It is better for this information to be available even in unpolished
  2327.  form than for it to be hidden out of embarrassment for its form.
  2328.  Before electronic technology, the effort of publishing was such that
  2329.  this information was never seen, and it was a waste, and and
  2330.  considered an insult to one's readers, to publish something which was
  2331.  not of high quality.  Nowadays, there is "publishing" at all levels,
  2332.  and both high quality and hasty documents have their value.    It is
  2333.  important, though, to make it clear what the quality of a document is
  2334.  when making a reference to it, to avoid disappointment.
  2335.  Monitoring the server log files will tell you which documents are
  2336.  really being read.  You can use your time most efficiently to improve
  2337.  the quality of those.  Of course, analysing the server log files also
  2338.  takes time!
  2339.  (Part of the Style Guide for Online Hypertext . Back to Within each
  2340.  doument, On to Background reading)
  2341.  
  2342.                                                                 Tim BL
  2343.                                                                       
  2344. Within each document
  2345.  
  2346.  This section of the style guide deals with the layout of text within
  2347.  a "document", the unit of retrieval of information on the web.
  2348.  To be completed.
  2349.  You should try to:
  2350.  
  2351.       Sign your work
  2352.       
  2353.       Give its status
  2354.       
  2355.       Make links into context .
  2356.       
  2357.       Use context-free document titles
  2358.       
  2359.       Format device-independantly
  2360.       
  2361.       Write for the printed work too
  2362.       
  2363.       Write readable text despite the links
  2364.       
  2365.  (up to overview , back to structure , on to testing )
  2366.  
  2367.                                                                 Tim BL
  2368.                                                                       
  2369. Background reading
  2370.  
  2371.  Some other documents which may be of relevance, if you are reading
  2372.  the Style Guide for Online Hypertext :
  2373.  
  2374.       The HTML Specification and references from it
  2375.  
  2376.  
  2377. T. Berners-Lee                                                       41
  2378.  
  2379.                                  WWW Server Guide)        14 July 1993
  2380.  
  2381.       
  2382.       A Beginner's Guide to writing HTML
  2383.       
  2384.       World-Wide Web server software - a list of pointers
  2385.       
  2386.       Web Ettiquette -- for Server Administrators
  2387.       
  2388.  (Back to testing, on to ...)
  2389.  
  2390.                               MAIL ROBOT
  2391.                                    
  2392.  The mail robot is a program which will accept incoming mail and allow
  2393.  remote users to:
  2394.  
  2395.       Subscribe to mailing lists (and unsubscribe)
  2396.       
  2397.       Retrieve information given a W3 addresss (URL)
  2398.       
  2399.  Originally from UC Berkeley, an enhanced robot is distributed as part
  2400.  of the world-wide web global information initiative . Futhur
  2401.  information available is:
  2402.  
  2403.   Help                    The help file for users of the robot service
  2404.                          
  2405.   Installation            Installation instructions for unix system
  2406.                          managers
  2407.                          
  2408.   Bugs                    Lists of improvements requested or needed.
  2409.                          
  2410.   Change history          A list of features introduced and bugs
  2411.                          fixed.
  2412.                          
  2413.   See also               Other WWW software
  2414.                          
  2415. Using the W3 mailing robot
  2416.  
  2417.  This robot maintains the W3 mailing lists, and allows W3 documents to
  2418.  be retrieved on request.
  2419.  You can subscribe or unsubscribe to any of the various WWW mailing
  2420.  lists by sending email to the robot "listserv@info.cern.ch" -- see
  2421.  the commands listed below.
  2422.  If you have any problems, requests or questions for a human being,
  2423.  mail "www-request@info.cern.ch". Lists are:
  2424.  
  2425.   www-announce            Anyone interested in WWW, who would like
  2426.                          information about new releases or new online
  2427.                          data available. Please refrain from posting
  2428.                          administrivia to this large list !
  2429.                          
  2430.   www-talk                Developers of WWW code, or those interested
  2431.                          in discussions of technical details
  2432.                          
  2433.  
  2434.  
  2435. T. Berners-Lee                                                       42
  2436.  
  2437.                                  WWW Server Guide)        14 July 1993
  2438.  
  2439.  You can also find information on WWW (as well as many other things!)
  2440.  by telnetting to info.cern.ch (no username, no password).
  2441.  If you want to pick up the WWW software, then use anonymous FTP to
  2442.  info.cern.ch and look in directory /pub/www. Subdirectories are src
  2443.  for the latest source packages, bin for executables for various
  2444.  machines, doc for "paper copies" of articles on WWW in PostScript and
  2445.  ASCII form. To read the latest documentation, use WWW !
  2446.  
  2447.   COMMANDS
  2448.  The commands understood by the listserv program are:
  2449.  
  2450.   HELP                    lists this file.  This is also sent whenever
  2451.                          a message to listserv is received from which
  2452.                          no valid command could be parsed.
  2453.                          
  2454.   HELP groupname          lists a brief description of the group
  2455.                          requested.
  2456.                          
  2457.   ADD listname            Add yourself to the list
  2458.                          
  2459.   DELETE listname         take yourself off the list
  2460.                          
  2461.   ADD address listname    Add yourself with a given mail address to
  2462.                          the given list. The address must not contain
  2463.                          spaces!
  2464.                          
  2465.   DELETE address listname
  2466.                           Remove the given name from the given list.
  2467.                          For all ADD/DELETE commands, mail is sent to
  2468.                          the address given to confirm the add or
  2469.                          delete operation.
  2470.                          
  2471.   SEND document-address   returns a document with the requested W3
  2472.                          address.
  2473.                          
  2474.   STOP                    Stop processing requests: ignore the rest of
  2475.                          the message. Needed if you send a signature
  2476.                          on the end of your message (or if some
  2477.                          gateway adds one). If in doubt, use it.
  2478.                          
  2479.  A command must be the first word on each line in the message.  Lines
  2480.  which do not start with a command word are ignored.  If no commands
  2481.  were found in the entire message, this help file will be returned to
  2482.  you. A single message may contain multiple commands; a separate
  2483.  response will be sent for each.
  2484.  
  2485.     Examples
  2486.     
  2487.  
  2488.         add www-announce
  2489.  
  2490.         add me@host.uni.edu www-announce
  2491.  
  2492.  
  2493. T. Berners-Lee                                                       43
  2494.  
  2495.                                  WWW Server Guide)        14 July 1993
  2496.  
  2497.         delete me@host.uni.edu www-talk
  2498.         
  2499.         send http://info.cern.ch/hypertext/DataSources/bySubject/Overv
  2500. iew.html
  2501.  
  2502.   SUBSCRIPTION
  2503.  If you are not sending mail from your preferred mail address, then
  2504.  you can use the second form of the command to give your mail address.
  2505.  If you are not on the internet, please convert your address into arpa
  2506.  stye. (For example, UK users please use international ordering
  2507.  joe@host.ac.uk) Just speficy the mailbox, without any spaces.
  2508.  If you omit the 'address' the command will assume the mailbox that is
  2509.  in the From: line of the message.  Note that SUBSCRIBE is a synonym
  2510.  for ADD; UNSUBSCRIBE for DELETE.
  2511.  Please note that is IS possible to add or delete someone else's
  2512.  subscription to a mailing list.  This facility is provided so that
  2513.  subscribers may alter their own subscriptions from a new or different
  2514.  computer account. There is therefore some potential for abuse; we
  2515.  have chosen to limit this by mailing a confirmation notification of
  2516.  any addition or deletion to the address added or deleted including a
  2517.  copy of the message which requested the operation.  At least you can
  2518.  find out who's doing it to you.
  2519.  Note that although you would mail submissions to a mailing list by
  2520.  addressing mail to e.g., www-talk@info.cern.ch, in a subscription
  2521.  request you specify the name of the list simply (without the
  2522.  @hostname part) as in the first example above.
  2523.  
  2524.   RETRIEVING DOCUMENTS
  2525.  The SEND command (or the WWW command which is equivalent) returns the
  2526.  document with the given W3 address, subject to certain restrictions.
  2527.  Hypertext documents are formatted to 72 character width, with links
  2528.  numbered. A separate list at the end gives the document-addresses of
  2529.  the related documents.
  2530.  If the document is hypertext, it links will be marked by numbers in
  2531.  brackets, and a list of document addresses by number will be appended
  2532.  to the message. In this way, you can navigate through the web, albeit
  2533.  only at mail speed.
  2534.  If you don't know where to start, try asking for one of
  2535.  
  2536.  
  2537.  http://info.cern.ch./hypertext/DataSources/bySubject/Overview.html
  2538.  http://info.cern.ch./hypertext/DataSources/bySubject/Physics/HEP.html
  2539.  http://info.cern.ch./hypertext/WWW/TheProject.html
  2540.  
  2541.  for lists of futher pointers.
  2542.  
  2543.   CAUTIONARY NOTE
  2544.  As the robot gives potential mail access to a *vast* amount of
  2545.  information, we must emphasise that the service should not be abused.
  2546.  Examples of appropriate use would be:
  2547.  
  2548.       Accessing any information about W3 itself;
  2549.       
  2550.  
  2551. T. Berners-Lee                                                       44
  2552.  
  2553.                                  WWW Server Guide)        14 July 1993
  2554.  
  2555.       Accessing any CERN and/or physics-related or network development
  2556.       related information;
  2557.       
  2558.  Examples of INappropriate use would be:
  2559.  
  2560.       Attempting to retrieve binaries or .tar files or anything more
  2561.       than directory listsings or short ASCCII files from FTP archive
  2562.       sites;
  2563.       
  2564.       Reading internet newsgroups which your site doesn't take;
  2565.       
  2566.       Repeated automatic use;
  2567.       
  2568.  There is currently a 1000 line limit on any returned file. We don't
  2569.  want to overload other people's mail relays or our server. We reserve
  2570.  the right to withdraw the service at any time. We are currently
  2571.  monitoring all use of the server, so your reading will not initially
  2572.  enjoy privacy. End of cautionary note.
  2573.  Enjoy!
  2574.  
  2575.                            The W3 team at CERN  (www-bug@info.cern.ch)
  2576.                                                                       
  2577. Installation
  2578.  
  2579.  Here are the steps necessary to install the Mail Robot product on
  2580.  your unix system.
  2581.  
  2582.   CUSTOMISATION
  2583.  Set up the variables in listserv.h and CommonMakefile to suit your
  2584.  site.
  2585.  
  2586.   POSTMASTER              The address from which messages appear to
  2587.                          come. Why not listserv? Perhaps to prevent
  2588.                          mail loops.
  2589.                          
  2590.   SECUREWWW               The executable W3 line mode browser (v1.3 or
  2591.                          later, so as to have the -listrefs option).
  2592.                          This is a separate product. For security, www
  2593.                          should be writable only by root.
  2594.                          
  2595.   SERVERDIR               The directory in which you want to put your
  2596.                          mailing lists and help about them.
  2597.                          
  2598.   COMPILE THE PROGRAMS
  2599.  Everything compiled on AEM's MicroVax II running ULTRIX 3.0 then
  2600.  TBL's NeXT without any problem at all. Your results may vary.
  2601.  
  2602.   CREATE YOUR SERVDIR
  2603.  wherever you specified in listserv.h. Install a HELP file, perhaps
  2604.  using the example-files/HELP in this directory as a template.
  2605.  
  2606.   SET UP AN ALIAS "LISTSERV"
  2607.  Make an alias in your /etc/aliases (or /etc/sendmail/aliases,
  2608.  
  2609. T. Berners-Lee                                                       45
  2610.  
  2611.                                  WWW Server Guide)        14 July 1993
  2612.  
  2613.  whatever you have) that points to this program, for example:
  2614.  
  2615.  
  2616.                 listserv:       "|/usr/local/mail/listserv"
  2617.                 robot:          "|/usr/local/mail/listserv"
  2618.  
  2619.  
  2620.   FOR EACH MAILING LIST
  2621.  Create a name.info file giving a bit of information about that
  2622.  mailing list. see the *.info files in the example-files subdirectory.
  2623.  Create a name file in the same directory, consisting of email
  2624.  addresses one to a line of subscribers to a group. If it is for a
  2625.  brand-new group, create an empty file. Remember that this file must
  2626.  be writable by the mail daemon. The name of the file is just the name
  2627.  of the group.
  2628.  Depending on how you have your mailing lists set up, you may need to
  2629.  add an alias to the /etc/aliases file for each of the mailing lists.
  2630.  For example:
  2631.  
  2632.         real-recipes: :include:/usr/local/mail/maillists/recipes
  2633.  
  2634.  So sending mail to real-recipes actually goes to each of the
  2635.  subscribers listed in /usr/local/mail/maillists/recipes
  2636.  
  2637.   INSTALL LISTSERV
  2638.  Install in the appropriate directory.  Edit the CommonMakefile and
  2639.  then
  2640.  
  2641.                 make install
  2642.  
  2643.   RUN NEWALIASES
  2644.  This gets sendmail to read the changes in /etc/aliases.
  2645.  
  2646.                 newaliases
  2647.  
  2648.   TRY IT OUT
  2649.  Send mail to listserv with body
  2650.  
  2651.  
  2652.                 HELP
  2653.  
  2654.  for example.  You should get a plain text version of the help file.
  2655.  
  2656. Mail Robot
  2657.  
  2658.  This is a "listserv" type program which maintains mailing lists, and
  2659.  allows W3 documents to be retrieved by electronic mail.
  2660.  
  2661.   Author:                 Various, modified by TBL.
  2662.                          
  2663.   Status:                 Source available  by anonymous FTP. (Oct 92)
  2664.                          
  2665.  
  2666.  
  2667. T. Berners-Lee                                                       46
  2668.  
  2669.                                  WWW Server Guide)        14 July 1993
  2670.  
  2671.   Current version:        1.0
  2672.                          
  2673.   Platforms:              Unix only.
  2674.                          
  2675.   More information:       Overview , Bugs , change history .
  2676.                          
  2677. Bugs
  2678.  
  2679.  This is a list of bugs in or improvements desired in the Mail Robot.
  2680.  See also the list of bug fixes .
  2681.  
  2682.       The INDEX command ought to be implemented, but for some reason
  2683.       always returns an empty list.  Occasionally it seems to work.
  2684.       
  2685. Change History
  2686.  
  2687.  Changes to the Mail Robot , in reverse chronological order:
  2688.  
  2689.   OCTOBER 1992
  2690.  TBL added information retrieval possibility using WWW. Release as an
  2691.  unsupported W3 product to those who ask for it.
  2692.  
  2693.   1991
  2694.  TBL rewrote str.c (used to overwrite its arguments).
  2695.  
  2696.   AEM
  2697.  A. E. Mossberg, aem@mthvax.cs.miami.edu made a couple minor changes,
  2698.  to make it slightly less UCSD-specific. He also added a README, and
  2699.  example files in the subdirectory example-files.
  2700.  
  2701.   ORIGIN
  2702.  Note this is NOT the bitnet LISTSERV program. The term "mail robot"
  2703.  is yused to attempt to prevent confusion between these two products,
  2704.  which have different functionality although they do basically the
  2705.  same sort of thing.
  2706.  This was the UCSD listserv program, which AEM retrieved from ucsd.edu
  2707.  by anonymous ftp, TBL retrieved from ftp.eff.org  As retrieved, from
  2708.  file://ftp.eff.org/pub/listserv2.shar, it consisted of the following
  2709.  files:
  2710.  
  2711.                         README
  2712.                         Makefile
  2713.                         commands.c
  2714.                         listserv.h
  2715.                         main.c
  2716.                         str.c
  2717.                         subscribe.c
  2718.  
  2719.    
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725. T. Berners-Lee                                                       47
  2726.  
  2727.